From bfe3346c33f0211c19ff24ca4346056b3c5f6b48 Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 29 Sep 2026 14:20:37 +0000 Subject: [PATCH] Pin Development Guidelines and add the project entry documents. The guidelines submodule records the reviewed commit so project rules stay discoverable without copying them into this repository. Co-authored-by: Cursor --- .gitmodules | 3 + AGENTS.md | 27 ++++++++ PROJECT.md | 61 +++++++++++++++++++ deps/development-guidelines | 1 + .../records/2026-09-29-guidelines-adoption.md | 40 ++++++++++++ policy/guidelines-adoption.md | 40 ++++++++++++ 6 files changed, 172 insertions(+) create mode 100644 .gitmodules create mode 100644 AGENTS.md create mode 100644 PROJECT.md create mode 160000 deps/development-guidelines create mode 100644 docs/records/2026-09-29-guidelines-adoption.md create mode 100644 policy/guidelines-adoption.md diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..ef67b32 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "deps/development-guidelines"] + path = deps/development-guidelines + url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Development-Guidelines.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b44552f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +# 项目工作入口 + +本项目采纳的通用规则：[核心规则](deps/development-guidelines/core/baseline.md)。 +采纳范围、生效状态及项目差异：[采纳记录](policy/guidelines-adoption.md)。 +项目事实、测试和环境入口：[PROJECT.md](PROJECT.md)。 + +- 启动：阅读以上短入口；只加载本次任务触发的专题。 +- 普通交付：[交付流程](deps/development-guidelines/workflows/delivery.md)。 +- 并行开发/正式测试/审核/合入：[共同基线与同步节点](deps/development-guidelines/standards/collaboration.md)，必须确认并实际同步最新权威目标。 +- Bug/异常：[系统性排障](deps/development-guidelines/workflows/debugging.md)。 +- 会话结束/换机器/换客户端/换执行者：[会话、执行者与机器交接](deps/development-guidelines/workflows/handoff.md)，状态写入任务主记录，不依赖本地会话历史。 +- 测试与验收：[验证标准](deps/development-guidelines/standards/verification.md)。 +- 模块/接口：[模块契约](deps/development-guidelines/standards/module-contracts.md)。 +- 错误合同：[可观测性](deps/development-guidelines/standards/observability.md)。 +- 其他专题：按 [任务索引](deps/development-guidelines/README.md) 选择。 + +项目补充硬边界： + +- 规范码以本仓 `errcode` 与 `domains` 为权威。消费方不得另起一套同义字符串。 +- 未知码回落 `sys.unknown_code`，HTTP 500，禁止当成功，禁止无条件重放。 +- 副作用为 `possible` 或 `unknown` 的码不得无条件重放。 +- 本仓不导入 Agent-Native、Agent-Squad 或 Logging-System。 + +任务权威：Gitea 仓库 `weichen/Error-Code-System` 的 Issue 与 Pull Request。 +规范性文档目录与过程记录位置：`policy/`；过程记录豁免目录 `docs/records/`。 +默认集成基线和提交身份：`main`。权威远端 `ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Error-Code-System.git`。 +共享环境/发布入口及授权：查询服务默认 `:8091`，仅本地组合根，无共享环境。 diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..0b7e515 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,61 @@ +# Error-Code-System 项目事实 + +工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。 + +## 仓库与操作 + +- 目标/产品边界：跨系统错误码目录、进程内错误类型，以及可独立运行的查询服务。不依赖 Agent-Native、Agent-Squad 或日志库。 +- 源码、资产、文档、机器契约位置：模块路径 `error-code-system`。包为 `errcode`、`domains`、`httpx`、`server`、`cli`、`conformance`。映射文档在 `docs/`。种子码以 Go 注册为权威，`domains/*.json` 为导出快照。 +- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Error-Code-System.git`，基线 `main`。 +- 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。消费方父仓 gitlink 才是它们使用的版本。 +- 发布线与批准版本/实际制品查询入口：无独立制品库。`go build -o bin/errcode .` 从当前提交构建。 +- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。 +- 任务唯一来源：Gitea `weichen/Error-Code-System` 的 Issue 与 Pull Request。 +- 规范性文档目录：`policy/`。 +- 过程文档仓/目录：`docs/records/`（项目内豁免）。 +- 交接记录位置：随任务主记录；需要落盘的交接放入 `docs/records/`。 +- 凭证查找入口及所需字段：本库不保存凭证。 + +## 依赖组合 + +| 逻辑 ID | 路径 | 角色 | +|---|---|---| +| development-guidelines | `deps/development-guidelines` | development-only | + +本库没有 Go 模块依赖。被消费时由父仓以 submodule 固定提交，例如 `deps/error-code-system`，并在父仓 `go.mod` 写： + +``` +require error-code-system v0.0.0 + +replace error-code-system => ./deps/error-code-system +``` + +克隆： + +```bash +git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Error-Code-System.git +``` + +## 验证命令 + +| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 | +|---|---|---| +| 文档 | 核对 `docs/` 映射与码常量一致 | 不代替 `domains` 测试 | +| 模块/接口 | `go vet ./... && go test -count=1 ./...` | 不启动长期服务 | +| 数据/权限/恢复 | 不适用数据库。注册表 `LoadJSON` 失败回滚由测试覆盖 | 无 | +| UI/执行后端 | 不适用图形界面。`go test ./server/... ./httpx/...` 覆盖 HTTP | 不覆盖消费方仓库 | + +改种子码后重写导出快照： + +```bash +WRITE_CATALOG=1 go test ./domains -run TestWriteCatalog -count=1 +``` + +## 环境与数据 + +| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 | +|---|---|---|---|---| +| 本地查询服务 | `GET /v1/codes` | 无远程写入 API；码表变更走本仓提交 | 无数据库，码在进程内注册表 | 重启进程 | + +共享项及 ACL：无。部署、迁移、发布的审批依据与负责角色：合并进 `main` 由仓库所有者批准。消费方升级必须单独提交父仓 gitlink。 +实际制品/配置/schema 的查询方法：`./bin/errcode export` 或 `GET /v1/export`，以当前进程加载的注册表为准。 diff --git a/deps/development-guidelines b/deps/development-guidelines new file mode 160000 index 0000000..26b562d --- /dev/null +++ b/deps/development-guidelines @@ -0,0 +1 @@ +Subproject commit 26b562d2e34fbc560711296a309c91c74ffc55b1 diff --git a/docs/records/2026-09-29-guidelines-adoption.md b/docs/records/2026-09-29-guidelines-adoption.md new file mode 100644 index 0000000..d518047 --- /dev/null +++ b/docs/records/2026-09-29-guidelines-adoption.md @@ -0,0 +1,40 @@ +# 接入开发规范并说明被父仓固定引用的方式 + +状态：已批准范围；owner：weichen；主任务：本仓接入提交。 +授权与交付终点：挂载 Development-Guidelines，补齐项目入口，并在 README 说明消费方如何用 submodule 与 `replace` 固定本库。不修改码值，不导入日志库。 +并行基线：Error-Code-System `main` @ `b67696d393e7abfbdd16fdde1064c07f5ecd2f72`。日期 2026-09-29。 + +## 问题与证据 + +本库已定义 `agent.*` 与 `squad.*` 种子码和映射文档，但消费方尚未把本库固定为 submodule。README 的依赖示例使用同级目录 `../Error-Code-System`，与各仓统一的 `deps/` 布局不一致。没有根 `AGENTS.md` 与采纳记录。 + +## 目标与边界 + +- 规范子模块放 `deps/development-guidelines` 并固定 SHA。 +- README 增加 `deps/error-code-system` 的消费示例，保留「本库不依赖另外三个业务仓」的边界。 +- 非目标：不改种子码；不把 Agent-Native 或日志库引进来。 + +## 选择与实施 + +过程记录放 `docs/records/`。映射文档保持在 `docs/`，因为它们描述当前码合同，不是某次任务证据。 + +## 兼容、迁移与恢复 + +同级目录 `replace` 对尚未迁移的旧工作区仍然有效。新消费方使用 `./deps/error-code-system`。回退本提交不影响已发布的码字符串。 + +## 验收 + +| 需求/验收条件 | 负责模块/契约或不变量 | 验证方法/用例 | 实际结果/证据 | +|---|---|---|---| +| 规范 gitlink 固定 | deps/development-guidelines | `git submodule status` | 计划阶段待执行 | +| 既有测试保持通过 | 全模块 | `go test -count=1 ./...` | 计划阶段待执行 | +| README 给出 deps 消费方式 | README | 人工阅读 | 计划阶段待执行 | + +| 用户/系统条件 | 检查层级与方法 | 预期结果 | 必需环境/授权 | +|---|---|---|---| +| 未知码 | conformance | 回落 `sys.unknown_code` | 无 | +| 别名 | `errcode show` 或单测 | 旧字符串回到规范码 | 无 | + +## 决策与剩余项 + +消费方（Agent-Native、Agent-Squad）在各自仓库提交 gitlink。本仓不记录那些父仓的 SHA。 diff --git a/policy/guidelines-adoption.md b/policy/guidelines-adoption.md new file mode 100644 index 0000000..6e4ac9a --- /dev/null +++ b/policy/guidelines-adoption.md @@ -0,0 +1,40 @@ +# 通用规范采纳记录 + +- 项目/负责人：Error-Code-System / 仓库所有者 weichen +- 状态：active +- 规范位置：`deps/development-guidelines` +- 规范性文档目录：`policy/` +- 过程文档位置：`docs/records/`（项目内固定目录豁免。码表与映射文档属于本代码仓的机器契约说明，仍放 `docs/`；方案与验证记录放 `docs/records/`。任务主记录在 Gitea Issue/PR。） +- 版本权威：父仓 gitlink；可读标签：无（内容版本 `0.1.0-draft.6`，提交 `26b562d2e34fbc560711296a309c91c74ffc55b1`） +- 批准/生效依据：本仓接入提交 +- 替代范围和迁移说明：无既有根 `AGENTS.md`。`docs/*.md` 继续作为码格式、治理和映射的单一说明，不迁入规范库。 + +| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 | +|---|---|---|---| +| core/baseline.md | 日常工作 | 错误码是跨系统合同 | manual | +| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 消费方依赖稳定码 | manual | +| standards/collaboration.md | 消费方 gitlink 升级 | 本仓不跟踪消费方分支 | manual | +| standards/verification.md | 目录治理测试 | `go test` 与 conformance | manual | +| standards/module-contracts.md | errcode/domains/httpx 边界 | 种子码集中注册 | manual | +| standards/observability.md | 稳定 code、信封、trace 头 | 本仓提供错误半边，日志库提供另一半 | manual | +| standards/documentation.md | 三层文档 | 映射文档留在本仓 `docs/` | manual | +| standards/multi-repo.md | 被其他仓以 submodule 消费 | 本仓不嵌套那些消费方 | manual | +| standards/failure-containment.md | 未知码回落 | fail-closed | manual | +| standards/security.md | 公开 message 与 reason | reason 可含调用方文本，不在本库收集凭证 | manual | +| standards/data-reliability.md | 无持久化码表 | 码表随版本发布，不在运行时改写 | 不适用独立存储专题 | +| standards/agent-execution.md | 不执行 Agent | 只提供 agent 域码 | 不适用 | +| standards/configuration.md | 无多实例配置 | serve 地址由 CLI 标志给出 | 不适用 | +| standards/release-operations.md | 无制品流水线 | 消费方固定 gitlink | 不适用 | +| workflows/automation.md | 无后台任务 | 库与按需查询 | 不适用 | + +## 项目差异 + +| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 | +|---|---|---|---| +| documentation.md 过程仓默认独立仓库 | `docs/records/` 豁免 | 个人项目。`docs/` 里的映射是契约说明，不是某次任务记录 | 对外发布码表版本时复查是否要把发布说明拆到过程记录 | + +## 本次升级或首次接入验证 + +- 子模块固定 `26b562d2e34fbc560711296a309c91c74ffc55b1`。 +- 挂载不改变 `go test` 行为。 +- 回退只恢复 gitlink 与入口文件，不改码值。