在依赖本地后台服务（守护进程）的应用中，只做小范围的代码修改

## 改代码前先读设计文档，弄清各个文件夹的作用 保持改动小巧，与仓库当前所面向的架构保持一致，并优先遵循已写入文档的守护进程/API 边界，而不是沿用来自正在被替换的旧实现的行为。 按职责而非按文件名来了解代码布局： - 后端包含命令行客户端、环回 HTTP 守护进程、各类服务、内嵌数据库存储、生命周期/回收器逻辑、运行时与工作区适配器，以及它们的测试。 - 桌面端或 Web 前端是一个瘦监督器和 UI 界面层，通过生成的类型化客户端连接到守护进程。不要把守护进程的逻辑搬进去。 - 文档目录存放当前的架构说明和状态说明。在改动生命周期、客户端、智能体、存储或守护进程的行为之前先阅读它们。 - 另有一个独立的测试目录，存放外部冒烟测试与端到端测试资产，包括全新安装的容器检查。 - CI 工作流定义是"必须通过什么"的参考依据。尽可能在本地复现那些命令。 在进行非琐碎的改动前，按以下顺序阅读：快速上手 README、文档索引、架构文档（心智模型、包布局、生命周期/会话/服务边界，以及承重性规则）、状态文档（今天主分支上已交付的内容与仍在推进中的内容），以及客户端文档（其预期形态）。如果仓库中还带有面向其他智能体工具的兼容性指针文件，应把它们当作指向唯一权威指南的重定向，而不是另一套独立的规则。 按职责而不是盲目搜索来定位入口点：命令实现、HTTP 控制器与 DTO、服务的读/写边界、领域词汇、端口契约、数据库查询与迁移，以及生成的数据库代码，各自都位于自己的包中。在引入新风格之前，先遵循邻近的命令与测试写法。 ## 运行项目自带的检查，界面改动要实际显示出来看 使用仓库自带的聚合命令，而不是临时自创命令。从仓库根目录出发，这些命令通常覆盖：lint（后端测试加上固定版本的 linter）、前端类型检查、从查询与 schema 重新生成数据库访问代码、重新生成 API 规范与前端类型，以及一个用于校验 CI 定义的本地工作流运行器（它可能需要容器套接字）。 在迭代过程中，直接运行组件级别的检查仍然值得：后端的构建、测试、启用竞态检测的测试、静态分析（vet）以及启动服务；前端的类型检查与构建。 当改动在 UI 中可见时，要真正使用项目的预览命令在会话中把它渲染出来并查看结果。不要只是描述这个改动应该长什么样。 ## 安装方式只推荐能自动更新的桌面应用 当一个项目有不止一条安装路径时，只有一条是权威的，指引必须指向那一条。 - 通过 release 发布的、可自动更新的桌面版构建是权威安装路径。首先把用户引导到那里。 - 某个遗留的包管理器渠道可能仍然可用，但已不再被推荐。如果最终版本已经发布且该包被冻结，它将不再收到任何更新。它仅仅作为一条入口通道，留给那些已经在 PATH 中拥有该命令的用户使用；在那里启动它会去获取并打开权威构建版本。 - 不要添加任何把已冻结的遗留渠道当作产品预期安装方式的功能、文档或流程。 ## 只改任务需要的部分，并遵循现有的代码划分 - 让每一处改动都与任务直接相关。除非任务明确要求，否则避免顺手清理、大范围重命名、格式化搅动、投机性抽象以及架构级重构。 - 遵循既有的包边界。客户端代码通过共享的客户端辅助函数调用守护进程的 HTTP 路由；它不得打开数据库、不得派生运行时，也不得直接调用适配器。 - 把每个命令保持在其相关的命令文件中，并按照邻近命令测试的风格用表驱动测试来覆盖它。 - 在客户端一侧镜像请求与响应 DTO，而不是把服务端控制器包导入客户端代码中，除非该依赖在这个包里已经既成事实。 - 通过专门的用法错误类型返回用法错误，使得客户端误用以其自己的状态码退出（例如 2），而运行时和守护进程故障则以通用失败码退出（例如 1）。 - 在向外呈现守护进程错误时保留 API 错误信封与请求 ID，而不是把它们压扁成纯字符串。 - 在任何执行 I/O 或阻塞工作的函数中，把取消/截止时间上下文作为第一个参数传入。 - 不要为一次性用例添加抽象。只有当一个辅助函数能消除多个真实调用点之间的重复时，才引入它。 - 测试应覆盖用户可见的行为以及正在被改动的边界：正常路径、校验与缺失参数、守护进程错误信封，以及任何破坏性操作的确认路径。 ## 不改动也不增加守护进程的网络入口 - 守护进程的主监听器保持绑定在环回地址上，并保持不做身份验证。不要更改它的绑定主机，也不要给它加上身份验证。 - 守护进程可以运行第二个可选启用的监听器，它绑定所有网络接口以供局域网访问，但只能在被明确启用时、只能置于 bearer 密码认证中间件之后、且只能提供应用 API。该监听器绝不能提供受环回限制的控制类路由，例如关机、遥测和远程控制。 - 如果这样的监听器是明文的、且仅面向受信任的家庭网络，那么这是一个刻意为之并记录在架构决策记录中的决定。在改动它之前先阅读那份记录。 - 不要添加任何其他面向网络的绑定。 - 命令行客户端保持为瘦客户端。不要把绕过守护进程 HTTP 路由的旧版进程内行为移植过来。 ## 保护保存的数据，不手动修改自动生成的数据库代码 - 不要存储派生出来的或面向展示的状态。应在服务读取时从持久事实（活动状态、终止标志，以及拉取请求/检查/评论等事实）推导出状态。 - 不要把一次失败或结果未知的运行时探测当作会话已死的证据。 - 不要强制删除仍有未提交改动的已注册工作树。 - 不要修改已经合并过的迁移。改为新增一个迁移。 - 不要手工编辑生成的数据库代码。改动查询或迁移，然后重新运行生成器。 - 变更事件从数据库触发器流入变更日志。除非架构明确发生变化，否则不要在 store 方法中添加一条并行的、手动的变更发射路径。 - 留意生成的 API 产物与手写 DTO 之间的漂移。控制器的响应结构位于单个 DTO 文件中，测试可能会断言客户端与 HTTP 层之间的线路兼容性。 - 不要在测试中添加网络调用，除非该包已经存在集成测试或端到端测试的既有模式。优先使用进程内测试服务器、伪实现和注入依赖。 - 不要提交本地运行状态、守护进程数据、临时工作树、构建产物或凭据。 - 把所有应用状态都保存在那个唯一的专用状态目录之下，并可通过已写入文档的环境变量覆盖。守护进程数据目录、运行中进程文件、工作树，以及桌面外壳的用户数据（浏览器缓存、Cookie、local 与 session 存储、崩溃转储）都必须解析到该目录之下。绝不要从操作系统默认的应用数据位置读取或向其写入。桌面端入口点会把外壳的用户数据路径固定到该目录；不要移除这个覆盖设置，也不要依赖默认路径。 ## 在手写的文件里修改API，再自动重新生成说明文件 守护进程 API 是代码优先的。OpenAPI 规范和前端类型都是生成产物，因此要修改源头并重新生成，而不是编辑输出结果。 - 修改定义请求与响应结构的 DTO 文件。 - 修改规范构建器的操作注册表，为任何新命名的类型添加一条 schema 名称条目。 - 使用仓库的聚合 API 命令重新生成，该命令会依次运行规范生成与类型生成。 - 用服务端 HTTP 包中的测试来验证；这些测试覆盖规范漂移以及路由与规范的一致性。它们并不覆盖生成的前端类型，那由一个独立的 CI 漂移检查任务负责。 - 把生成的规范和生成的前端类型与源码改动一起提交。CI 会重新生成这两者，如果提交的版本已过期就会失败。 - 手工镜像的客户端 DTO 仍然是一条刻意保留的手动边界，不由生成器产出。 ## 每个变更请求（拉取请求）只处理一个问题 - 从主分支拉出新分支，除非你是在明确地继续一个已有的拉取请求。 - 一个拉取请求只对应一个议题。如果被要求做另外的工作，就另建一个分支和拉取请求。 - 使用约定式提交信息前缀，例如 feat、fix、docs、test 和 chore。 - 在拉取请求正文中说明有意省略的部分，尤其是当前身实现所支持的行为多于当前重写版本的领域范围时。 - 先运行范围最窄的相关测试，然后再运行与你所改动区域相对应的仓库命令与 CI 命令。