Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

docs: add a protocol reference page for custom clients

Đang mở
  • Có gì không ổn?
#286 2 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@kachamsiddarth đang làm issue này rồi.

Từ ngày 21/10/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

documentation good first issue hacktoberfest website

The server speaks protocol v1 now (#285), but the only description of it is a section of server/setup.mdx. Anyone writing their own client (a mobile app, a CLI, a different widget) needs one page that lists every part, every error code and a request they can paste into a terminal. This issue is that page.

What to do

  • New page website/src/content/docs/server/protocol.mdx, title Protocol, added to the Server sidebar in website/astro.config.mjs (lines 121 to 128), after Setup. Cover:
    • How to ask for v1: "protocol": 1 in the body, or the x-chatcops-protocol: 1 header. The response then has x-chatcops-protocol: 1. Without either, the server answers in the 0.5 format, which goes away in 1.0.
    • The request body: the fields in chatRequestSchema (packages/server/src/config.ts, lines 101 to 123) with their limits, plus protocol.
    • Every part in WirePart (packages/core/src/protocol/v1.ts, lines 50 to 99), one short paragraph or table row each, with an example line. Say which ones the server sends today (start, text-start, text-delta, text-end, tool-call, tool-result, lead-captured, error, finish) and that the others (source, handoff, agent-message, suggestions) are reserved for later features.
    • Framing: one data: <json> line per part, data: [DONE] once at the end, : ping comments after 10 s of silence, clients ignore unknown part types, and a stream without finish was cut off.
    • Errors before the stream: every status and code from packages/core/src/protocol/errors.ts, with the JSON body shape and Retry-After.
    • Errors during the stream: the error part's codes, retryable, and scope for budget_exceeded.
    • A curl example: curl -N -X POST http://localhost:3001/chat -H 'Content-Type: application/json' -d '{"protocol":1,"conversationId":"test-1","message":"Hi"}', followed by what it prints.
    • import type { WirePart } from '@chatcops/core/protocol' for TypeScript clients.
  • In website/src/content/docs/server/setup.mdx, keep the "Response format" section short: the two formats in one paragraph, and a link to the new page for the details. Move the parts list and the status table there.

Where to look

  • packages/server/src/http.ts, which does negotiation, statuses, pings and [DONE]
  • packages/server/tests/http.test.ts for real request and response examples
  • packages/core/src/protocol/ for the types and the status map

Acceptance criteria

  • New server/protocol.mdx in the sidebar, covering the points above
  • Every part and error code in v1.ts and errors.ts is on the page, and nothing that isn't
  • The curl example's output on the page is real. You don't need an API key: run the Express example (packages/server/src/examples/express-server.ts) with provider: scriptedProvider([textStep('Hello!')]) from @chatcops/core/testing/provider, and don't commit that change
  • pnpm --filter @chatcops/website build succeeds
  • Changeset: pnpm changeset --empty (docs only)

Please get this merged by Dec 8, since the v0.6 release notes link to it.

Want to work on this? Comment below and I'll assign it to you. Please take one issue at a time, branch off dev, and open your PR against dev with Closes #<this issue number>. Setup notes (pnpm, build before test) are in CONTRIBUTING.md.

Ngôn ngữ chính
TypeScript
Star
13
Fork
7
Merge trung bình
3 giờ 41 phút
Pull request đã merge (30 ngày)
155

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của codercops/chatcops

Tất cả issue của codercops/chatcops

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.