mcpx AGENTS.md

仓库指南

项目结构与模块组织

MCPX 是运行在开发环境中的 MCP Runtime（网关），Go module 为 mcpx，需 Go 1.26.1+（以 go.mod 为准）。

路径	说明
cmd/mcpx-server/	可执行入口（main、子命令如 oauth-register）
internal/observation/	观测系统：timeline、render、diff、event、store、width 等，用于实时观测、事件流、变更摘要、终端展示和模型友好交互（最近新增 observation_bridge.go）
docs/plans/、docs/specs/	实现计划与设计规格
bin/	本地构建产物（已 gitignore）
~/.mcpx/	运行时数据（配置、SQLite、日志、任务），不在本仓库

本地产品文档 prd/、docs/superpowers/ 被 .gitignore 排除，勿提交。

版本策略

• 永远不要考虑兼容以前的版本。
• 新实现只维护当前契约；不得为旧版本保留别名、适配器、迁移分支、旧 Schema、旧工具入口或兼容测试。
• 发生契约变更时，直接同步修改实现、文档和测试；旧行为应删除，不应继续隐藏保留。
• 除非用户在当前请求中明确要求，否则不讨论、不实现历史版本兼容方案。

构建、测试与开发命令

命令均来自 README 与 .github/workflows/ci.yml：

# 编译
go build -o bin/mcpx-server ./cmd/mcpx-server

# 单测（CI 同款）
go test ./... -count=1

# 竞态检测
go test -race ./... -count=1

# 格式检查（仅 cmd + internal）
test -z "$(gofmt -l ./cmd ./internal)"

# 静态检查
go vet ./...

# 发布构建（CGO 关闭，与 CI/GoReleaser 一致）
CGO_ENABLED=0 go build -o bin/mcpx-server ./cmd/mcpx-server

本地运行：先执行 ./bin/mcpx-server workspace register /path/to/project，再执行 ./bin/mcpx-server 启动服务；终端观测使用 ./bin/mcpx-server observe <workspace-name>。版本：./bin/mcpx-server -version。 发版：推送 v* 标签触发 GoReleaser（见 .github/workflows/release.yml、.goreleaser.yaml）。

编码风格与命名

• 使用 gofmt；改动保持与现有包风格一致（小写包名、导出类型 PascalCase、YAML 字段 snake_case tag）。
• 平台相关文件用 _unix.go / _windows.go / _darwin.go 后缀（见 changeset、environment、cmd）。
• 优先改 internal/ 对应包；工具面注册与 HTTP 网关在 internal/server/。
• 最小充分改动；不要引入未使用的依赖。

测试指南

• 框架：Go 标准库 testing。
• 命名：*_test.go，与被测包同目录（如 internal/auth/token_test.go）。
• 改后端逻辑后应补/跑相关包测试；宣称完成前至少对改动包执行 go test ./path/to/pkg -count=1，合并前宜跑 go test ./... -count=1（与 CI 一致）。
• 单测默认用于本地验证；是否纳入提交由用户当轮决定。

提交与 PR

• 历史风格：Conventional Commits，subject 中文动词开头，例如：
  • feat(cli): 增加 oauth-register 子命令
  • fix(oauth): 持久化 DCR 客户端
  • docs(readme): 补充接入说明
  • chore(repo): … / ci(release): …
• 禁止 agent 自动 commit / push。若建议提交：先展示变更摘要与完整 commit message，经用户明确确认后再执行。
• PR：说明动机与行为变化；关联 issue（如有）；涉及鉴权/网关/配置时写清兼容与风险；CI 须绿（test、gofmt、vet、race、build）。