Deepsight

Appearance

Agent 开发指南 ​

本文档面向参与 Deepsight 研发的 AI agent 和人类协作者。它从仓库内 .agent/ 控制面提炼公开稳定规则，保留协作流水线、任务分层和验证纪律， 但不发布当前任务状态、历史归档和内部反馈 inbox。

1. 文档边界 ​

Deepsight 的文档分为两类：

  • docs/：长期项目文档，面向用户、贡献者和维护者。
  • .agent/：AI 协作控制面，面向具体开发过程。

公开官网只发布稳定协作规则。以下内容不进入官网：

  • .agent/current.md，因为它只代表当前 L/XL 任务状态。
  • .agent/archive/，因为它是历史计划和阶段上下文。
  • .agent/man.md，因为它是人类维护的内部反馈 inbox。
  • 一次性环境噪声、长命令日志、未公开路线图和凭据。

2. 阅读顺序 ​

Agent 在修改代码前应先建立最小充分上下文：

  1. 读取项目规则，确认不可越过的边界。
  2. 读取当前项目上下文，理解实现阶段和已完成能力。
  3. 读取路线图，确认任务属于哪个阶段。
  4. 读取工作流，选择合适的任务大小和协作流水线。
  5. 检查验证清单和代码-文档映射。

公开文档中，长期架构以 项目概览、 数据流、RPC 契约 和 工程设计 为准。Agent 文档只约束协作方式，不替代 架构文档。

3. 任务大小 ​

Deepsight 使用任务大小驱动 AI 协作。Commit 是最终打包单位，不是计划单位。

类型适用场景典型产物
S: Small小 bug、小测试、小文档修正简短计划、实现、验证摘要
M: Change Unit一个清晰工程边界mini spec、实现、测试、文档同步
L: Milestone多个 Change Unit 组成的阶段交付阶段计划、分批实现、验收记录
XL: Epic完整能力域设计、里程碑拆分、多轮交付

Change Unit 应有一句话目标、明确边界和可执行验证。它通常对应一个 commit； 如果同时触及契约、实现和文档，可以拆成多个 commit。

4. 协作流水线 ​

Deepsight 的核心协作思想是一条可中断、可恢复、可审查的流水线：

text
STATUS -> PLAN -> REFINE* -> DRAFT -> IMPLEMENT -> VERIFY/REVIEW* -> SYNC -> CLOSE -> COMMIT

各阶段含义如下：

  • STATUS：报告当前阶段、任务大小、事实来源、目标、已完成步骤、下一步、阻塞点和脏工作区。只读，不改文件。
  • PLAN：产出计划。S/M 任务可用短计划；L/XL 任务应说明里程碑、Change Unit 和验收方式。只读，不改文件。
  • REFINE：根据反馈修订计划。最新版计划加上已接受反馈，构成当前执行约束。
  • DRAFT：把已接受的 L/XL 计划写成任务草案。小任务通常不需要这个阶段。
  • IMPLEMENT：按当前计划实现。所有改动必须能追溯到任务目标。
  • VERIFY：运行可行验证，记录未执行验证的原因和残余风险。
  • REVIEW：以代码审查视角检查当前变更，优先发现 bug、回归风险和测试缺口。
  • SYNC：同步代码、文档和任务记录。行为、契约、配置或命令语义变化时必须检查文档影响。
  • CLOSE：收束任务，说明完成内容、验证结果、残余风险和建议 commit 信息。不创建 commit。
  • COMMIT：只有在人类明确要求时才创建 commit，并且只包含本任务相关文件。

REFINE、VERIFY 和 REVIEW 可以重复出现。PAUSE 和 RESUME 可以用于暂停 和恢复流水线，但不能绕过项目规则、权限要求或高风险变更的计划门槛。

5. 高风险变更 ​

以下改动必须先给出短计划，再进入实现：

  • Protobuf 契约或生成的 API 代码。
  • eBPF C 代码、BPF 生成逻辑或需要特权加载的 Probe 行为。
  • 运行时配置优先级、传输行为或默认监听地址。
  • TLS、安全边界、权限边界和网络暴露面。
  • 架构文档或代码-文档绑定规则。

这些领域的变更需要明确验证路径。如果受 sudo、网络或本地环境限制，应记录未验证项、 原因和残余风险。

6. 仓库边界 ​

维护 Deepsight 时应保持以下边界：

  • proto/ 是契约真源，api/ 是生成输出；两者目录结构保持一致。
  • 3rd/libbpf/ 是 vendored 第三方代码，除非任务明确要求，否则视为只读。
  • .agent/ 用于 AI 协作控制，docs/ 用于长期项目文档。
  • CHANGELOG 只在发布或人类明确要求时更新。
  • 历史归档只能解释过去决策，不能覆盖当前规则和上下文。

7. 配置与安全默认值 ​

配置行为必须保持可解释和可测试：

  • 配置优先级保持 flag > env > config file > defaults。
  • TCP 默认应绑定 127.0.0.1，避免默认暴露到公共接口。
  • 不得引入意外的 0.0.0.0 监听行为。
  • TLS 当前是显式 stub；当 tls.enabled=true 时，启动应明确失败，直到真实 TLS 支持完成。

8. 验证纪律 ​

验证选择应匹配改动风险：

  • 普通 Go 逻辑：优先运行 make test。
  • 构建链路变更：运行 make build。
  • Protobuf 变更：运行 make proto 和 make test。
  • eBPF 变更：运行 make build，并说明真实加载是否完成。

命令安全本身也是验证的一部分。格式化、生成、清理、安装、真实 Probe 运行和 bpftool 可能修改仓库、依赖权限或触碰系统状态；在纯计划或审查阶段不应运行。

9. 文档同步 ​

改动完成前，应通过代码-文档映射检查文档影响：

  • proto/**/*.proto 或 api/**/*.pb.go 变化，需要检查 RPC 和 proto 文档。
  • internal/config/** 或 configs/*.example.yaml 变化，需要检查配置和快速开始文档。
  • Probe pipeline 变化，需要检查数据流、工程设计和开发环境文档。
  • Server ingestion、dispatch 或 buffer 语义变化，需要检查服务端状态和数据流文档。
  • 构建脚本或开发脚本变化，需要检查开发环境和快速开始文档。

文档同步不等于扩大范围。只有行为、契约、设置或命令语义发生变化时，才应更新长期文档。

Apache 2.0 Licensed

Copyright © Deepsight