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 <cursoragent@cursor.com>
2026-09-29 14:20:37 +00:00
parent b67696d393
commit bfe3346c33
6 changed files with 172 additions and 0 deletions
@@ -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
@@ -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`，仅本地组合根，无共享环境。
@@ -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`，以当前进程加载的注册表为准。
@@ -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。
@@ -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 与入口文件，不改码值。