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 49e6dd1e0f
commit 57c049bd38
6 changed files with 183 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,29 @@
+# 项目工作入口
+
+本项目采纳的通用规则：[核心规则](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/workflows/design-verification.md)，按增量明确验收、独立测试及故障范围。
+- 错误与过程事件：[可观测性](deps/development-guidelines/standards/observability.md)。
+- 拆仓与 submodule：[多仓库与固定版本组合](deps/development-guidelines/standards/multi-repo.md)。
+- 其他专题：按 [任务索引](deps/development-guidelines/README.md) 选择。
+
+项目补充硬边界：
+
+- `contract` 不依赖内核、产品类型、数据库或本仓以外的运行时；错误码字符串与 Error-Code-System 的 `agent.*` 规范码对齐，旧字符串只作为别名由错误码库解析。
+- 未知结果保持 Unknown，不降级为成功或失败；副作用为 possible/unknown 时禁止无条件重放。
+- 缺能力即拒绝，不静默降级到 Stub。Workspace 路径授权不是 OS 沙箱。
+- 依赖仓版本以本仓 gitlink 为准，不执行 `submodule update --remote`。
+
+任务权威：Gitea 仓库 `weichen/Agent-Native` 的 Issue 与 Pull Request。
+规范性文档目录与过程记录位置：`policy/` 放项目规则；`docs/records/` 为过程记录豁免目录（方案、验证、交接）。项目规范与过程记录不进通用规范库。
+默认集成基线和提交身份：`main`；提交身份沿用本机 git 作者，不在文档中写死密钥或个人 fork URL。
+共享环境/发布入口及授权：无共享运行环境。权威远端 `ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git`。
@@ -0,0 +1,52 @@
+# Agent-Native 项目事实
+
+工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。
+
+## 仓库与操作
+
+- 目标/产品边界：独立的 Agent 执行基础库。提供执行契约（contract）、执行端口（exec）、自研运行时（runtime）、外部适配器（adapters）与行为验收（conformance）。不实现小队编排，不依赖 Core 或 Squad。
+- 源码、资产、文档、机器契约位置：Go 源码在仓库根包目录；模块路径 `agent-native`；人类文档在根 `README.md`、`docs/`、`policy/`；过程记录在 `docs/records/`；机器契约以 `contract` 包类型为准。
+- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git`，集成基线 `main`。
+- 并行共同基线记录位置、合入通知/主动检查方式：任务主记录在 Gitea Issue/PR；合入前在本仓 `main` 上 `git fetch` 并确认 HEAD。
+- 发布线与批准版本/实际制品查询入口：当前无独立制品仓库。可构建性以本仓 `main` 的 `go test` 为准；依赖子模块版本以 gitlink 为准，不把工作区未提交文件当发布组合。
+- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。本机提交不代替远端合并。
+- 任务唯一来源：Gitea `weichen/Agent-Native` 的 Issue 与 Pull Request。
+- 规范性文档目录：`policy/`。
+- 过程文档仓/目录：`docs/records/`（项目内豁免，理由见 [采纳记录](policy/guidelines-adoption.md)）。
+- 交接记录位置：随任务主记录；需要落盘的交接放入 `docs/records/`。
+- 凭证查找入口及所需字段：模型与 Runner 凭证由调用方注入，不入库。本仓不保存密钥字段的值。
+
+## 依赖组合
+
+| 逻辑 ID | 路径 | 角色 |
+|---|---|---|
+| development-guidelines | `deps/development-guidelines` | development-only，规范文本 |
+| error-code-system | `deps/error-code-system` | build-required（接入后） |
+| logging-system | `deps/logging-system` | build-required（接入后） |
+
+克隆：
+
+```bash
+git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git
+# 已克隆时：git submodule update --init --recursive
+```
+
+构建、审核和发布固定父仓 gitlink，不执行 `submodule update --remote`。
+
+## 验证命令
+
+| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 |
+|---|---|---|
+| 文档 | 人工核对 `AGENTS.md`、`PROJECT.md`、`policy/` 相对链接 | 不证明运行时行为 |
+| 模块/接口 | 仓库根：`go vet ./... && go test -count=1 ./...` | 需要 Go 1.27；不覆盖真实模型端点 |
+| 数据/权限/恢复 | 不适用独立数据库。契约测试覆盖副作用分类与取消传播 | 不证明调用方产品库的持久化 |
+| UI/执行后端 | `go test ./adapters/... ./runtime/... ./conformance/...` | 默认 fake/stub；真实模型需调用方提供端点，本命令不覆盖 |
+
+## 环境与数据
+
+| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 |
+|---|---|---|---|---|
+| 本地开发 | 本机工作区与 `go test` | 本机 git 提交 | 无共享数据库；会话文件由调用方 Workspace 决定 | 重新 clone 父仓并 `submodule update --init --recursive` |
+
+共享项及 ACL：无。部署、迁移、发布的审批依据与负责角色：当前库不独立部署；合并进 `main` 由仓库所有者批准。
+实际制品/配置/schema 的查询方法：阅读当前 `main` 的 `contract` 包与 `go.mod`，不以历史 README 快照代替。
@@ -0,0 +1,54 @@
+# 接入开发规范并为执行契约对齐错误码与日志
+
+状态：已批准范围（实现进行中）；owner：weichen；主任务：本仓接入提交。
+授权与交付终点：在 Agent-Native 内挂载规范子模块、补齐项目入口，并把执行错误与日志接到 Error-Code-System / Logging-System。不改 Gitea 权限，不发布制品。
+并行基线：Agent-Native `main` @ `49e6dd1e0fc65de7f259f21d2f63c56e5b165a48`；Development-Guidelines `26b562d2e34fbc560711296a309c91c74ffc55b1`；Error-Code-System `b67696d393e7abfbdd16fdde1064c07f5ecd2f72`；Logging-System `7f5972007bdcb6047ce7f95ee891f53e0af9d136`。日期 2026-09-29。
+
+## 问题与证据
+
+四个基础库此前没有统一的项目入口，也没有把 Development-Guidelines 固定进父仓。Agent-Native 的 `contract.ErrorCode` 仍是短字符串（如 `canceled`），与错误码库的 `agent.*` 规范码只在映射文档中对应，调用方无法从错误值直接得到规范码。runtime 没有可替换的结构化日志，失败只能靠返回值。
+
+经验检索：规范库与两个基础库均为新仓，无已验证经验条目。
+
+## 目标与边界
+
+- 规范以 `deps/development-guidelines` 的 gitlink 为版本权威。
+- `contract.ErrorCode` 的取值改为 `agent.*`；`contract.Error` 提供 `ErrorCode()` / `ErrorFields()`，使日志库能识别错误且 `contract` 不导入错误码模块。
+- pitransport 对外错误码同步为规范码；`CANCELLED` 并入 `agent.canceled`，`MISSING_TARGET` 并入 `agent.missing_deliverable`。
+- runtime 与 native adapter 接受可选 `*logsys.Logger`，nil 时使用空日志器。
+- 非目标：不改 Squad 编排；不把本仓变成错误码目录的第二权威；不自动跟踪子模块上游分支。
+
+## 选择与实施
+
+子模块统一放 `deps/`，与后续各仓布局一致。错误码常量改值而不是在调用点拼接前缀，避免两套字符串长期并存。`contract` 只增加鸭子方法，不 `import error-code-system`，保持该包零外部依赖。
+
+1. 挂载 `deps/development-guidelines` 并提交入口文档。
+2. 挂载 `deps/error-code-system`、`deps/logging-system`，`go.mod` 用相对 `replace`。
+3. 修改 `contract` 与 `adapters/pitransport` 的错误码取值，补日志钩子与 `scripts/submodule-consistency.sh`。
+4. 仓库根 `go test` 作为本模块出口。
+
+## 兼容、迁移与恢复
+
+错误码取值变更对按旧字符串比较的调用方是破坏性变更。错误码库已把旧值登记为别名，`Registry.Resolve` 仍可解析旧字符串。`agent-system-multi` 若硬编码旧码，需在其自己的消费提交里跟进；本仓 gitlink 未进主仓组合之前不影响主仓构建。
+
+回退：父仓 PR 恢复旧 gitlink 与旧常量值。无数据库迁移。暂停条件：`go test` 失败或子模块 SHA 无法从批准远端获取。
+
+## 验收
+
+| 需求/验收条件 | 负责模块/契约或不变量 | 验证方法/用例 | 实际结果/证据 |
+|---|---|---|---|
+| 规范入口可发现且版本固定 | 根 AGENTS.md / gitlink | `git submodule status`；打开相对链接 | 计划阶段待执行 |
+| contract 错误码为 agent.* 且鸭子方法可被日志识别 | contract.Error | `go test ./contract/...` | 计划阶段待执行 |
+| pitransport 历史码映射到规范码 | adapters/pitransport | `go test ./adapters/pitransport/...` | 计划阶段待执行 |
+| 可选日志器为 nil 时行为不变 | runtime / adapters/native | `go test ./runtime/... ./adapters/native/...` | 计划阶段待执行 |
+
+| 用户/系统条件 | 检查层级与方法 | 预期结果 | 必需环境/授权 |
+|---|---|---|---|
+| 全新 clone 后可测试 | `git clone --recurse-submodules` 后 `go test` | 通过 | 能访问 Gitea SSH |
+| 旧错误字符串仍可被错误码库解析 | 错误码库别名测试（该库既有用例） | 别名回到规范码 | Error-Code-System 源码 |
+| 未知结果与缺能力 | contract/conformance 既有用例 | 不降级、不回落 Stub | 无 |
+| 无日志器的既有调用 | runtime/native 既有测试 | 保持通过 | Go 1.27 |
+
+## 决策与剩余项
+
+多级副本由各父仓 gitlink 锁定；Agent-Squad 构建时只采用 Agent-Squad 自己的 `replace`。一致性脚本在本仓接入两个基础库后启用。验证证据在实现完成后写入同目录的验证记录，不把本方案改称已完成。
@@ -0,0 +1,44 @@
+# 通用规范采纳记录
+
+- 项目/负责人：Agent-Native / 仓库所有者 weichen
+- 状态：active
+- 规范位置：`deps/development-guidelines`
+- 规范性文档目录：`policy/`
+- 过程文档位置：`docs/records/`（项目内固定目录豁免。当前为个人维护的基础库，单独过程仓会让每份记录都变成跨仓 gitlink；任务主记录仍在 Gitea Issue/PR。豁免一经登记，过程记录不得再写入 `policy/` 或规范库。）
+- 版本权威：父仓 gitlink；可读标签：无（内容版本 `0.1.0-draft.6`，提交 `26b562d2e34fbc560711296a309c91c74ffc55b1`）
+- 批准/生效依据：本仓接入提交；草案审阅完成后随该提交生效
+- 替代范围和迁移说明：本仓此前没有根 `AGENTS.md`。接入后以本文件与根入口为准，不在规范库内保存项目事实。
+
+| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 |
+|---|---|---|---|
+| core/baseline.md | 日常工作 | 所有改动都要守硬边界 | manual |
+| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 单人维护仍需要可交接的任务记录 | manual |
+| standards/collaboration.md | 并行共同起点、节点同步与陈旧候选拒绝 | 本仓会被 Agent-Squad 以 gitlink 消费 | manual |
+| standards/verification.md | 验证与结论 | 仓库根 `go vet` / `go test` | manual；命令见 PROJECT.md |
+| workflows/design-verification.md、standards/testability.md、standards/failure-containment.md | 契约、适配器与故障分类 | 执行器失败必须可定位且不扩大工具范围 | manual |
+| standards/module-contracts.md | contract/exec/runtime/adapters 边界 | 公开端口已按层拆分 | manual |
+| standards/observability.md | 错误码、过程事件 | 与 Error-Code-System / Logging-System 对齐 | manual |
+| standards/agent-execution.md | 能力协商与后端回退 | 本仓就是执行契约的权威 | manual |
+| standards/multi-repo.md | submodule 与固定组合 | 规范与基础库以 gitlink 锁定 | manual |
+| standards/security.md | 路径授权、工具范围、凭证 | 凭证不入库；路径授权不等于 OS 沙箱 | manual |
+| standards/documentation.md | 三层文档 | `policy/` 与 `docs/records/` 已分开 | manual |
+| standards/data-reliability.md | 执行副作用与重放 | 无本仓数据库；适用副作用分类，不扩展成存储设计 | manual |
+| standards/configuration.md | 调用方注入的模型与工具配置 | 本仓不自带多实例部署配置 | manual |
+| standards/release-operations.md | 独立发布流水线 | 当前无制品仓库与部署入口 | 不适用 |
+| workflows/automation.md | 定时与后台任务 | 本仓无 daemon | 不适用 |
+
+## 项目差异
+
+| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 |
+|---|---|---|---|
+| documentation.md 过程仓默认独立仓库 | 过程记录放 `docs/records/` | 个人基础库；风险是记录与代码同 PR 时容易把证据写成第二权威。任务状态仍只认 Gitea Issue/PR | 出现第二名维护者或对外发布流程时复查 |
+
+默认做法差异说明理由；硬边界冲突须有明确有效决策，不能用此表自授权。建议不采用无需登记。
+
+## 本次升级或首次接入验证
+
+- 入口：根 `AGENTS.md`、`PROJECT.md` 指向 `deps/development-guidelines`。
+- 子模块：`deps/development-guidelines` 固定 `26b562d2e34fbc560711296a309c91c74ffc55b1`。
+- `.gitmodules` 使用批准的上游 SSH URL，不含本机路径或凭证。
+- 执行方式保持 manual：挂载 Markdown 不自动改变 CI。
+- 回退：恢复本提交之前的 gitlink，并删除根入口与 `policy/guidelines-adoption.md` 中对应条款；无已生效的 CI 或权限变更需要另恢复。