Skip to content

feat: 外部集成扩展与 CLI（本地 API 服务 + meebox CLI） - #164

Merged
huhamhire merged 15 commits into
devfrom
feat/integration-cli
Jul 1, 2026
Merged

feat: 外部集成扩展与 CLI（本地 API 服务 + meebox CLI）#164
huhamhire merged 15 commits into
devfrom
feat/integration-cli

Conversation

@huhamhire

@huhamhire huhamhire commented Jul 1, 2026

Copy link
Copy Markdown
Owner

概述

「外部集成扩展与 CLI」特性线（目标 0.9.0）：主进程内置本地 API 服务，并提供独立跨平台 CLI meebox，使外部 agent / 工具 / 脚本可集成应用的 PR 浏览与评审 Agent 能力。默认关闭、开启即强制 token 鉴权；CLI 只读取向、不含写操作。

设计见 docs/arch/04-integration，用法见 docs/guide/06-cli.md。

包含

  • 服务端：config service 段 + token 生成/热重建监听器；ApiServer（内置 http + 极简路由 + 常数时间鉴权 + 统一封套 + 错误码映射）；12 只读端点（categories / pr 列表·详情·diff·动态·提交·评审人 / agent 状态·历史·review·instruct·chat）；SV 错误码域；写工具硬拒绝。
  • 设置页：新增「集成」分区（开关 · http://host:port · token 显隐/复制/再生成 · 0.0.0.0 安全警示）；四语 locale。
  • CLI（cli/，独立 Go module）：命令树 + 连接解析（flag > env > cli.yaml > 本机自动发现）+ 默认 YAML 输出（--output json 供机器）+ 只读边界；配置 ~/.code-meeseeks/cli.yaml 与 GUI 隔离；遵循标准 HTTP(S)_PROXY。
  • CI/发布：release.yml 加 Go 交叉编译矩阵（Windows/macOS .zip、Linux .tar.gz）随同一 Release 产出；独立 ci-cli.yml PR 门禁（路径过滤 cli/**）。
  • 测试：CLI↔契约集成测试（httptest）+ render/settings 单测 + shared pr-filter 纯谓词单测；本地与 GitHub 均可跑、不触第三方模型。
  • 文档：设计（arch 04）+ 使用说明（guide 06）+ AGENTS CLI 工程规范；顺带 AGENTS.md 瘦身（发布/CHANGELOG 细节下沉 packaging-release、目录树改用途导向）。

测试

  • 桌面侧：lint / typecheck（全 15 包）/ test（含新增 shared）/ build 均通过。
  • CLI 侧：go vet / go test / go build 通过。
  • 端到端：对本机开启的服务用 meebox 实测只读命令、安全边界（401→2 / 404→3 / 写工具拒绝），以及真实 /describe 写路径。

说明

  • CLI 二进制随发版产出（本 PR 合入 dev 后，发 0.9.0 时经 tag 触发）。
  • 详见关联里程碑 0.9.0 · 外部集成扩展与 CLI。

🤖 Generated with Claude Code

huhamhire and others added 15 commits June 30, 2026 21:52
@huhamhire @claude
docs(arch): 新增外部集成扩展与 CLI 设计文档
47ebd30 
为 0.9.0「外部集成扩展与 CLI」方向沉淀设计：

- 服务监听与本地 API：主进程内置 HTTP API（IPC 之外第二前端），默认关闭、
  强制 bearer token、loopback 默认 / 可选 0.0.0.0、固定默认端口 18765、只读边界
  （写工具硬拒绝）、路由复用 service 层、端点表与 SV 错误码领域。
- CLI 工具：Go 技术栈与「同仓独立 cli/ 目录、不打进安装包」的内嵌评估、命令树、
  本机零配置自动发现（读 ~/.code-meeseeks/config.yaml）、输出与退出码、跨平台分发与 CI。
- 同步 arch README / 00-overview 模块地图与 ROADMAP 交叉链接。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
feat(cli): 搭建 meebox CLI 工程脚手架
3fd604a 
独立 Go module（顶层 cli/，不纳入 npm/Nx），作为本地 API 的瘦客户端：

- 命令树（cobra）：categories、pr（list/show/diff/activity/commits/reviewers）、
  agent（status/history/review/instruct/chat）；全局 flag --api-url/--token/--output/--quiet。
- 连接与鉴权解析：flag > env > CLI 配置文件 > 本机 ~/.code-meeseeks/config.yaml 自动发现。
- HTTP client：bearer 鉴权 + { ok, data } / { ok:false, error } 响应封套解析。
- 输出与退出码：JSON 输出 + 0/1/2/3 退出码映射（text 表格化待后续）。
- agent instruct 前置只读白名单（describe|review|ask|improve），写工具拒绝。

按设计文档契约实现（server 端单独实现）。本地 go vet / build / test 均通过。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
feat(desktop): 实现外部集成本地 API 服务端（监听 + 鉴权 + 只读端点）
4f31eaf 
主进程内置 HTTP API（IPC 之外的第二前端），复用同一 ControllerContext 与 service 层把只读
PR / Agent 能力暴露给外部 CLI / 工具。默认关闭、开启即强制 bearer token 鉴权。

- 配置：config.yaml 新增 service 段（enabled / host / port=18765 / token，全默认）；
  config:setService 热重建监听器、config:generateServiceToken 重新生成 token。
- 错误码：新增 SV（service）领域 + ESV0000~0004（经 HTTP 返回外部客户端，不走渲染层 i18n）。
- api-server：内置 http + 极简路由 + 常数时间 token 比对 + 统一响应封套 + 错误→状态码映射；
  12 端点（categories / prs 列表 + 详情 diff·动态·提交·描述·评审人 / agent 状态·历史·review·
  instruct·chat）。生命周期随 app 启停、按 service.enabled 决定是否监听，监听失败非致命。
- 只读边界：instruct 仅放行 describe/review/ask/improve，写工具硬拒绝（403）。
- 薄连接层：PR 列表的一/二级过滤 + 检索谓词与分类标签下沉为 @meebox/shared 纯函数，
  渲染层侧栏与 API 路由共用同一份语义（消除重复），api-server 仅做解析 + 委派。
- findPrOrThrow 改抛 AppError(PR_NOT_FOUND)，API 可映射 404、GUI 亦得正确 i18n。

设计见 docs/arch/04-integration/01-service-api.md。本地 lint / typecheck / test / build 均通过。
设置页 UI 单列后续。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
feat(desktop): 设置页新增「集成」分区配置本地 API 服务
073b125 
设置页新增独立「集成」分区，可视化管理本地 API 服务监听（见上一提交的服务端）：

- 开关 + 监听地址 http://<host>:<port> 两输入框组合（host 自由输入，保存时做简单合法性
  校验），开关仅决定是否监听、host/port/token 任何状态下均可编辑。
- bearer token：显示 / 隐藏 / 复制 / 重新生成（即时写盘生效）；启用且无 token 时自动生成。
- 监听非 loopback 地址（0.0.0.0 / 局域网 IP）时给出安全警示。
- 四语 locale 同步（新增「集成」分区名与服务监听文案）。
- CHANGELOG 增「本地 API 服务」Unreleased 条目（CLI 待随发布产出后再补）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
ci: release 工作流新增 meebox CLI 跨平台交叉编译矩阵
ff39add 
cli/ 为纯 Go、无 CGO，单 ubuntu runner 即可交叉编译全平台：

- 矩阵出 Windows x64 / macOS arm64 / Linux x64·arm64 二进制，打 .zip（win）/ .tar.gz（unix）
  + .sha256，随桌面安装包挂到同一个 GitHub Release（CLI 不打进安装包，是独立可分发物）。
- -ldflags -X …/cmd.version 注入版本号；仅 tag 触发上传，workflow_dispatch 仅编译冒烟。
- 不设 Release 正文（由桌面 build job 注入），仅追加产物，避免覆盖。
- CHANGELOG 补「命令行工具 meebox」条目（CLI 现随发布产出），本版重点改为「外部集成与 CLI」。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
ci: 新增 meebox CLI 独立门禁流水线
650c2b1 
cli/ 为独立 Go module，与 Node/Nx 的 CI 分开成独立 workflow：路径过滤只能加在 on 层
（不能按 job 过滤），独立成一条流水线才能做到仅当 cli/ 变更时才跑 go vet / test / build，
既隔离 Go 工具链、又省 CI 分钟。ci.yml 触发器保持不动，避免影响分支保护必检项。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
feat(cli): 默认输出改 YAML（类 k8s -o yaml），--output yaml|json
75c85cd 
CLI 主消费者是第三方 agent，但集成方传 flag 无门槛，故默认可面向人类优化体验：

- 默认输出 YAML——结构化又比裸 JSON 可读（类 kubectl -o yaml）；--output json 供机器/agent。
- YAML 与 JSON 皆为对响应数据的通用转换（json 解码 → 重新编码），不做逐命令表格 / formatter，
  免去手写响应 struct 的契约同步负担。复用既有 yaml.v3 依赖，无新增。
- 同步 cli/README 与设计文档 02-cli 的输出模式说明。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
ci: release 的 GUI 构建 job 由 build 更名为 gui
d624f79 
与并列的 cli job 对称，明确 release 内 GUI / CLI 两条产物线的划分。release 保持单 workflow
双 job（按 tag 原子发版、发到同一 Release），不拆分——路径触发那套只适用于按变更跑的 CI。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
feat(cli): CLI 配置文件改用 ~/.code-meeseeks/cli.yaml
aa902df 
原先读 <user-config-dir>/meebox/cli.yaml 会另起一个配置根，与产品单一数据目录约定
（~/.code-meeseeks/）不一致。改为 ~/.code-meeseeks/cli.yaml：与 GUI 的 config.yaml 同目录、
独立文件，隔离二者配置且单一可发现。抽 appHome() 复用同一 home 解析。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs(guide): 新增 CLI 使用说明
1e45845 
新增 docs/guide/06-cli.md（面向用户）：开启本地 API 服务 → 获取 CLI → 连接方式（含本机零配置
自动发现）→ 命令表 → 输出格式与退出码 → 安全须知；更新 guide README 索引，并与设计文档 02-cli 互链。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
test: 补 CLI↔契约集成测试与 shared PR 过滤单测
9777cfe 
- CLI（Go）：httptest 契约 mock 起在进程内跑命令，断言各命令的 method/path/query/鉴权头/
  请求体、yaml/json 渲染、退出码映射（401/403→2、404→3），以及写工具客户端硬拒绝。
- render：可注入 Stdout/Stderr 输出 seam + ExitCodeFor / 输出格式单测。
- settings：加 isolateHome，隔离本机 ~/.code-meeseeks 使解析测试本地 / CI 都 hermetic。
- @meebox/shared：新增 test target + pr-filter 纯谓词单测（渲染层侧栏与 API 共用同一份语义）。
- 全部零外部依赖、不触第三方模型，本地与 GitHub 均可跑。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
chore(cli): 补全 Go 工程 gitignore
7ff84d2 
补 Go 专有、根 .gitignore 未覆盖的忽略项：测试二进制（*.test）、覆盖率 / 剖析输出
（*.out / *.prof）、go workspace 文件（go.work / go.work.sum）。exe 与 dist/ 依赖根规则全局忽略。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
ci: CLI 的 macOS 发布产物改用 zip
9bafd79 
macOS 与 Windows 统一用 .zip（Finder 原生一步解压、贴合 Apple 工具链，Linux 仍用 .tar.gz）。
Linux runner 上 zip 保留 darwin 二进制的可执行位，解压即可运行。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs: 补 CLI 代理说明与 AGENTS CLI 工程规范
dc41d7b 
- guide 06-cli：新增「网络代理」段（CLI 遵循标准 HTTP(S)_PROXY / NO_PROXY，loopback 直连）。
- arch 02-cli：补代理行为说明；发布产物命名更新为 Windows/macOS .zip、Linux .tar.gz。
- AGENTS.md：新增「CLI 工程（cli/）」段（独立 Go module / 本地命令 / 双 CI / 只读边界 / 契约同步）；
  仓库结构对齐（cli/ 树、services/api-server、shared 的 pr-filter、docs/guide）；
  CHANGELOG 撰写风格与 i18n 要点由密集单行改为列表排版。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs: 瘦身 AGENTS.md，发布/CHANGELOG 细节下沉 packaging-release
62b05f0 
AGENTS.md 每会话整篇进上下文，精简其固定开销：

- 发布前置清单（版本号/CHANGELOG/校对）+ `-dev` 版本号规则 + CHANGELOG 撰写风格下沉到
  docs/development/packaging-release.md；AGENTS 只留 ⚠️ 前置警示 + 指针。
- pr-agent 运行时 / shim 深坑收成一条指针（机制与铁律已全在 02-agent/05）。
- 仓库结构树改用途导向（去具体文件名，各目录留一句职责）；i18n 三条、内部包两步登记改列表排版。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire huhamhire added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 1, 2026
@huhamhire
huhamhire merged commit 14fb95b into dev Jul 1, 2026
2 checks passed
@huhamhire
huhamhire deleted the feat/integration-cli branch July 1, 2026 03:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

0.9.0 · 外部集成扩展与 CLI

Development

Successfully merging this pull request may close these issues.

1 participant

@huhamhire