Skip to content

docs(api): index the AI conversation domain and its v0.4.0 endpoints - #1073

Open
JoAdo07 wants to merge 1 commit into
Tencent:mainfrom
JoAdo07:docs/1022-api-readme-ai-domain
Open

JoAdo07 wants to merge 1 commit into
Tencent:mainfrom
JoAdo07:docs/1022-api-readme-ai-domain

Conversation

@JoAdo07

@JoAdo07 JoAdo07 commented Nov 18, 2026

Copy link
Copy Markdown

What changed

docs/api/README.md 开篇声称索引与 internal/httpapi/server.go 注册的路由保持一致,但表格只覆盖了通过 manifest 暴露的 capabilities。整个 AI 对话域 /api/assistant/*(32 条路由)以及共享 AI 定时任务(2 条)都不在其中——包括 v0.4.0 新增的诊断导出 GET /api/assistant/generations/{generationId}/diagnostics 和对话内安装 CLI POST /api/assistant/cli-install。按 main 上的 server.go 逐条比对,本文件缺 34 条路由,读者据此写出的对接代码会漏掉整个助手域。

这个 PR 把缺口补上:

  • ### AI 对话(助手):32 行「方法 / 路径」索引表,置于原索引末尾。
  • ### 共享 AI 定时任务:2 行索引表。
  • ## AI 对话:诊断导出与对话内安装 CLI:两个 v0.4.0 端点的契约说明——状态码、响应字段、脱敏边界、?download=1 的下载文件名,以及可直接运行的 curl 示例。

内容取自 handler 实现(assistant_diagnostics.go、assistant_cli_install.go、internal/domain/assistant_diagnostics.go),而不是取自最早描述这两个端点的提案文档,因此状态码与字段名与代码一致。

Closes #1022

Scope

  • Platform core / API / runner
  • Public adapter / deployment
  • Classic
  • Portable
  • Shared behavior contract
  • Installer / CLI
  • Documentation only

Compatibility

无运行时变化,只新增文档段落,不改动任何已有行(+83 / -0)。

docs/api/openapi.yaml 有意未改:它是 MCP 工具 schema 的生成来源(internal/mcpserver/schema.go 从 apidocs.OpenAPI 构建),把助手端点写进去会改变对外暴露的工具集合,属于需要维护者决定的范围,不适合夹带在补索引的文档 PR 里。若维护者希望助手域也进入 OpenAPI 契约,我可以另开一个 PR。

Validation

实际执行过的检查:

# 1. 路由对齐:server.go 中 /api/assistant/* 与 /api/shared-schedule-tasks*
#    逐条与 README 表格比对(两侧都抹掉 {param} / :param)
-> 34/34 命中,缺失 0,多余 0

# 2. 交叉编译
GOOS=linux GOARCH=amd64 go build ./...            -> exit 0

# 3. 在 WSL 中运行交叉编译出的测试二进制
cd internal/httpapi
GOOS=linux GOARCH=amd64 go test -c -o httpapi.test .
./httpapi.test -test.run TestOpenAPIContractIsServedFromBinary -test.timeout 120s
-> PASS (0.15s),200235 bytes

未运行 / 受限项:

  • 完整 go test ./...:当前主机是 Windows,运行器代码使用 syscall.Kill、syscall.Setpgid、syscall.Stat_t,无法在 Windows 上构建,只能在 Linux 主机或 CI 上跑。本 PR 未改动 Go 代码。
  • python3 scripts/check-public.py:本机只有 python(3.13),无 python3,无法按原命令执行。

Safety

  • I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
  • I preserved user files and unrelated changes.
  • I updated generated Classic host bundles when applicable. (不适用:纯文档改动)
  • I documented third-party content and licensing changes when applicable. (不适用)

docs/api/README.md claims to mirror the routes registered in
internal/httpapi/server.go, but the index stopped at the manifest-exposed
capabilities. The /api/assistant/* domain (32 routes, including the two
v0.4.0 additions for diagnostics export and in-conversation CLI install)
and the shared AI schedule task routes were absent, so the file pointed
readers at a contract that no longer described the server.

Add both index tables and document the diagnostics and cli-install
endpoints: methods, status codes, response fields, the redaction
boundary and curl examples, taken from the handlers rather than from the
proposal that first described them.

Refs Tencent#1022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: API 索引漏掉 AI 对话(/api/assistant,32 个路由)与共享 AI 定时任务,v0.4.0 的诊断导出/CLI 安装没有公开契约

1 participant