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 7f5972007b
commit 0ea2ad297a
6 changed files with 170 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,28 @@
+# 项目工作入口
+
+本项目采纳的通用规则：[核心规则](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/standards/configuration.md)。
+- 其他专题：按 [任务索引](deps/development-guidelines/README.md) 选择。
+
+项目补充硬边界：
+
+- 本库只依赖标准库。识别错误码使用 `ErrorCode()` / `ErrorFields()` 鸭子接口，不 `import error-code-system`。
+- 写前脱敏覆盖 JWT、sk-key、Bearer、api_key、password 形状；采集服务写入时再脱敏一次。
+- 异步队列满时丢弃最新一条并计数，不阻塞业务 goroutine。
+- 追踪头为 `X-Trace-Id`。`trace_id` 回答哪一次请求，不替代调用方自己的 `run_id`。
+
+任务权威：Gitea 仓库 `weichen/Logging-System` 的 Issue 与 Pull Request。
+规范性文档目录与过程记录位置：`policy/`；过程记录豁免目录 `docs/records/`。
+默认集成基线和提交身份：`main`。权威远端 `ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git`。
+共享环境/发布入口及授权：采集服务默认 `:8092`。配置了 token 时要求 `Authorization: Bearer` 或 `X-Log-Token`。令牌值不入库。
@@ -0,0 +1,57 @@
+# Logging-System 项目事实
+
+工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。
+
+## 仓库与操作
+
+- 目标/产品边界：结构化日志库与可独立部署的采集服务。把一次请求的日志和错误码对齐到同一个 `trace_id`。不导入错误码模块。
+- 源码、资产、文档、机器契约位置：模块路径 `logging-system`。包为 `logsys`、`sink`、`redact`、`config`、`slogadapter`、`server`、`cli`、`conformance`、`examples/trace`。配置示例在 `docs/example.json`。
+- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git`，基线 `main`。
+- 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。消费方用自己的 gitlink 固定版本。
+- 发布线与批准版本/实际制品查询入口：无独立制品库。`go build -o bin/logctl .` 从当前提交构建。
+- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。
+- 任务唯一来源：Gitea `weichen/Logging-System` 的 Issue 与 Pull Request。
+- 规范性文档目录：`policy/`。
+- 过程文档仓/目录：`docs/records/`（项目内豁免）。
+- 交接记录位置：随任务主记录；需要落盘的交接放入 `docs/records/`。
+- 凭证查找入口及所需字段：采集 token 来自服务配置或环境，字段名为 token / `X-Log-Token`，值不入库。进程内日志还可由 `LOGSYS_CONFIG`、`LOGSYS_LEVEL`、`LOGSYS_SERVICE`、`LOGSYS_REDACT` 覆盖。
+
+## 依赖组合
+
+| 逻辑 ID | 路径 | 角色 |
+|---|---|---|
+| development-guidelines | `deps/development-guidelines` | development-only |
+
+本库 Go 依赖只有标准库。`examples/trace` 是独立模块，用相对路径引用本库与同级检出的 Error-Code-System，不把错误码库变成主模块依赖。
+
+被消费时：
+
+```
+require logging-system v0.0.0
+
+replace logging-system => ./deps/logging-system
+```
+
+克隆：
+
+```bash
+git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git
+```
+
+## 验证命令
+
+| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 |
+|---|---|---|
+| 文档 | 核对 `docs/integration.md` 与示例 | 不证明消费方已接线 |
+| 模块/接口 | 仓库根：`go vet ./... && go test -count=1 ./...` | 不含 `examples/trace`（独立模块） |
+| 数据/权限/恢复 | 文件滚动与采集 JSONL 由 sink/server 测试覆盖 | 无共享数据库 |
+| 跨库追溯示例 | 在 `examples/trace`：`go test ./...` | 需要同级目录 `../../../Error-Code-System` 或该 go.mod 的 replace 目标存在 |
+
+## 环境与数据
+
+| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 |
+|---|---|---|---|---|
+| 本地采集器 | `GET /v1/logs`、`logctl query` | `POST /v1/logs` | 配置的 JSONL 文件，默认由 CLI `--data` 指定 | 重放该 JSONL；SSE 游标过期后从查询接口对账 |
+
+共享项及 ACL：配置 token 时写入与读取都要带令牌。部署、迁移、发布的审批依据与负责角色：合并进 `main` 由仓库所有者批准。
+实际制品/配置/schema 的查询方法：以运行中的配置文件与 `LOGSYS_*` 环境变量为准，不以 `docs/example.json` 代替现场配置。
@@ -0,0 +1,41 @@
+# 接入开发规范并说明 deps 消费方式
+
+状态：已批准范围；owner：weichen；主任务：本仓接入提交。
+授权与交付终点：挂载 Development-Guidelines，补齐项目入口，并在 README 写明父仓 `deps/logging-system` 的引用方式。不导入错误码模块，不改变日志条目字段。
+并行基线：Logging-System `main` @ `7f5972007bdcb6047ce7f95ee891f53e0af9d136`。日期 2026-09-29。
+
+## 问题与证据
+
+README 的依赖示例是同级目录 `../Logging-System`。四个仓库约定把子模块放在 `deps/`。本仓没有根工作入口，规范版本也无法随父仓以外的方式固定到本仓自己的历史里。
+
+## 目标与边界
+
+- `deps/development-guidelines` 固定到已审阅提交。
+- README 给出 `replace logging-system => ./deps/logging-system`。
+- `examples/trace` 继续用独立模块的相对 replace，便于在两个仓库并列检出时运行，不把错误码库引进主模块。
+- 非目标：不改 sink、脱敏或采集 API。
+
+## 选择与实施
+
+先提交规范挂载与入口，再补 README 的消费说明。验证仍是仓库根 `go test`，外加示例模块测试。
+
+## 兼容、迁移与恢复
+
+旧的同级 `replace` 继续可用于尚未改布局的工作区。新父仓使用 `deps/`。回退本提交不改变日志格式。
+
+## 验收
+
+| 需求/验收条件 | 负责模块/契约或不变量 | 验证方法/用例 | 实际结果/证据 |
+|---|---|---|---|
+| 规范版本固定 | gitlink | `git submodule status` | 计划阶段待执行 |
+| 主模块测试通过 | 全部非示例包 | `go test -count=1 ./...` | 计划阶段待执行 |
+| 示例仍能引用错误码库 | examples/trace | `go test` | 计划阶段待执行 |
+
+| 用户/系统条件 | 检查层级与方法 | 预期结果 | 必需环境/授权 |
+|---|---|---|---|
+| 带 ErrorCode() 的错误 | logsys 测试 | 条目含 code | 无 |
+| 脱敏 | redact/conformance | 密钥形状被替换 | 无 |
+
+## 决策与剩余项
+
+Agent-Native 与 Agent-Squad 各自锁定本库 SHA。本仓不记录父仓提交。
@@ -0,0 +1,40 @@
+# 通用规范采纳记录
+
+- 项目/负责人：Logging-System / 仓库所有者 weichen
+- 状态：active
+- 规范位置：`deps/development-guidelines`
+- 规范性文档目录：`policy/`
+- 过程文档位置：`docs/records/`（项目内固定目录豁免。集成说明留在 `docs/integration.md`，因为它描述当前合同而不是某次任务。方案与验证放 `docs/records/`。任务主记录在 Gitea Issue/PR。）
+- 版本权威：父仓 gitlink；可读标签：无（内容版本 `0.1.0-draft.6`，提交 `26b562d2e34fbc560711296a309c91c74ffc55b1`）
+- 批准/生效依据：本仓接入提交
+- 替代范围和迁移说明：无既有根 `AGENTS.md`。
+
+| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 |
+|---|---|---|---|
+| core/baseline.md | 日常工作 | 日志是失败定位的另一半 | manual |
+| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 排障会直接使用本库 | manual |
+| standards/collaboration.md | 消费方固定版本 | 本仓不跟随消费方分支 | manual |
+| standards/verification.md | 并发、脱敏、排空 | conformance 与 `go test` | manual |
+| standards/observability.md | trace、级别、重放 | 本仓实现日志半边 | manual |
+| standards/configuration.md | 文件、环境变量、出口 | `config.Load` / `LOGSYS_*` | manual |
+| standards/security.md | 脱敏与采集 token | 写前与入库前各脱敏一次 | manual |
+| standards/failure-containment.md | 队列满丢弃最新一条 | 不阻塞业务 goroutine | manual |
+| standards/module-contracts.md | 不导入错误码库 | 鸭子接口是稳定边界 | manual |
+| standards/documentation.md | 三层文档 | `docs/` 与 `docs/records/` 分开 | manual |
+| standards/multi-repo.md | 被 submodule 消费；示例模块用相对 replace | 主模块不嵌套错误码库 | manual |
+| standards/data-reliability.md | JSONL 采集文件 | 无事务数据库；文件是日志投影 | manual |
+| standards/agent-execution.md | 不执行 Agent | 只记录调用方给出的字段 | 不适用 |
+| standards/release-operations.md | 无制品流水线 | 消费方固定 gitlink | 不适用 |
+| workflows/automation.md | 无独立定时任务 | 异步批导出是库行为，不是运营自动化 | 不适用 |
+
+## 项目差异
+
+| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 |
+|---|---|---|---|
+| documentation.md 过程仓默认独立仓库 | `docs/records/` 豁免 | 个人项目。风险同其他三仓 | 采集服务对外长期运行时复查 |
+
+## 本次升级或首次接入验证
+
+- 子模块固定 `26b562d2e34fbc560711296a309c91c74ffc55b1`。
+- `examples/trace` 仍使用自己的 `go.mod` replace，不改为依赖 `deps/` 下的错误码副本。
+- 回退只恢复规范 gitlink 与入口文件。