KonghaYao - 江夏尧

Designer of Fenix OS | Agent Builder from Peri Code!

[KonghaYao - 江夏尧 @konghayao]

@DashHuang 想要，软件工厂有这个机器就如虎添翼了

[KonghaYao - 江夏尧 @konghayao]

@yulinxuanzhi https://t.co/10CM95yAXf
V1 大重构中，国庆回来发布正式版本

[KonghaYao - 江夏尧 @konghayao]

分享一下 Fenix AOS v1 大重构的经验，我们重新编写了整个 TS 的前后端插件体系，设计并解耦分离了类似于 “微 Nextjs” 的架构。

每个独立的包能够独立挂载其前后端，外壳进行封装。此次大重构几乎更新了所有的代码，由 Deepseek V4.1 Flash + Peri Code 完成。

重构经验：
1. 定义架构上的权威文档，一定要定义好

2. 然后初步实现一个 demo template code（这个非常重要，有实现将会让后续的大 ultracode 非常通顺）

3. /ultracode 按照 demo 以及权威文档，最大并发档次，sonnet 模型，并发完成多个模块的新增与重构，注意保持 test 的模块通过和 typecheck

4. /ultracode 开始进行完整的各个模块的链接，并发进行，完成之后通过集成测试

5. /ultracode 扫描整个项目和每个模块，对齐前后端规范，遇到问题，就直接修复

我们在这次重构中还适配了新的 /multitask 模式，非常适合细小 BUG 的快速修复，不久将会直接作为 peri 的 builtin skill

[KonghaYao - 江夏尧 @konghayao]

@simon_he1995 很正常，这个模型非常贵，而且烧

[KonghaYao - 江夏尧 @konghayao]

Fenix AOS 在开发过程中也是一堆 slop，一堆过程文档，所以我们花时间到“权威文档”这个概念上，所有的派生过程文档均可以被删除。

同时，在 Peri 开发过程中发现，Peri 偶然的一个 code-index skill 使得 peri 构建出了一套代码索引结构文档，这个赋予了 peri 在搜索复杂大型仓库时的业务语义到代码的具体映射，极大提升了检索效率。故不久研究完毕将会实装这个 code-index skill

[KonghaYao - 江夏尧 @konghayao]

分享一下我们的 AGNETS.md 里面的核心工程原则，这个工程原则极大提高了 LLM 在我们项目中的稳定性，在10w 行级别的大重构中发挥了优秀的作用。

[KonghaYao - 江夏尧 @konghayao]

@yifanxu_ephai 我觉得学习语言，学习思路才是最重要的。

需要什么依赖实现什么功能，解决什么问题在什么语言里面都是通用的。

很多时候没有最佳，整个过程是哪个顺手哪个先来，落地之后，思路才会顺畅，然后才会思考逐步升级可靠性，稳定性等。

[KonghaYao - 江夏尧 @konghayao]

https://t.co/gjKgcyP6D7
原始定义在这里，工程原则未进行改动过，v1 大重构还需要点时间合入

[KonghaYao - 江夏尧 @konghayao]

下面是原始正文，针对各自的项目，需要稍微修改使用
# CLAUDE.md

## 核心工程原则

1. **架构与领域优先**：计划阶段应以理想架构为目标，明确业务目标、领域边界、模块职责、依赖方向和数据流，形成符合领域规律、面向长期维护且可持续演进的设计后再进入编码；不得以短期实现便利牺牲整体设计。设计必须完整，实现应当克制：不做推测性抽象，抽象延迟到第二个真实用例出现时才引入，单一场景直接实现。
2. **追求优雅的代码模块**：模块应高内聚、低耦合，通过精简且稳定的接口封装内部复杂度，使职责、命名、依赖和扩展方式清晰自然；代码按单一职责拆分，单个文件不得超过 500 行，接近上限时应优先重构模块边界。
3. **保持边界与数据流清晰**：协议模型、领域模型、持久化模型和视图模型不得相互泄漏；数据必须在边界处完成校验和独立转换，避免跨层共享可变状态。
4. **安全与隔离默认开启**：所有功能均按多租户、多用户场景设计，明确认证、授权和数据隔离边界；遵循最小权限原则，任何外部输入均视为不可信，敏感信息不得进入代码、日志或响应。
5. **面向并发与故障设计**：后端应主动考虑幂等性、竞态、事务边界、超时、取消、重试、背压和资源释放；不得通过无边界重试、吞错或隐式共享状态掩盖问题。
6. **保障完整前端体验**：前端应控制渲染成本、异步状态和并发请求，保持清晰的 UI 结构；用户流程必须覆盖加载、空状态、错误、重试、反馈和可访问性。
7. **复用稳定的业务语义**：优先复用已有模块和能力，但不要仅因代码外形相似而过早抽象；确需重复时，必须注释说明其独立演进或暂不抽象的原因。新增依赖前先核查项目已有依赖（根 `package.json` 与 `packages/` workspace）能否满足需求，不得臆断已有库缺少功能——先查阅文档和类型定义；确需引入时优先成熟且维护良好的库，不重复实现通用功能。
8. **为未来维护者保留上下文**：代码、注释、测试和架构文档是跨越时间的协作媒介。非显然的设计决策、兼容约束、已知缺陷和临时方案，必须记录原因、影响范围、潜在风险及移除条件；技术债务应关联可追踪任务，关键架构决策应同步到 ADR，禁止留下缺少上下文的 `TODO`。
9. **确保变更可验证、可观测、可回滚**：每项改动都应行为可测试、运行状态可观测、故障可定位，并兼顾向后兼容和回滚路径；错误与日志必须保留诊断上下文，但不得泄露敏感信息。
10. **删除优于兼容**：内部路径重构时直接删除过时实现，禁止新增兼容层、deprecated shim 或双写逻辑；对外契约（`/api/*` 等稳定接口、数据库迁移）的兼容性按协议契约单独评估，属于合同义务而非迁就旧代码。

> **变更速查**：通常提交前运行 `bun run precheck`；修改前端后额外运行 `bun run build:web`；修改 schema 后运行 `bun run db:generate --name <module>-<change>` 和 `bun run db:migrate`；涉及存量数据搬迁、修复或回填时，DDL 后还要运行 `bun run run-data-migrations`。

[KonghaYao - 江夏尧 @konghayao]

@a129h windows coding agent 用 ps1 非常难受

[KonghaYao - 江夏尧 @konghayao]

@realWeZZard 已经结束力，资本市场没给你机会，那就是没有

[KonghaYao - 江夏尧 @konghayao]

@akazwz_ 居然还竖中指

[KonghaYao - 江夏尧 @konghayao]

@dingyi ？？？

[KonghaYao - 江夏尧 @konghayao]

这就涉及到有状态运行时的问题了，Go 服务端请求可以保证内存控制在请求级别的回收。Agent 属于是有状态的执行器，那么常见问题有

1. 隐式引用关系管理不当+长生命周期对象巨多。（举个例子）维持一个不断增长的超长的 session list，它的周期=执行周期，它需要被不断使用以及追加/修改，并且被各种插件/调用方操作并持有关系。长时间内存慢慢涨，这个非常难避免，排查半天可能是插件/底层库/不规范写法，而非你的问题。Zen Code 就是因为这个夭折的。

2. 超高速小对象的内存碎片化。每次 Deepseek V4 Flash 的 SSE 请求数量需要做小对象聚合及销毁操作，反复的小对象申请与销毁、加工、转换对 GC 处理有要求，不想碰底层相关调优那么基本都会有内存尖峰的问题。叠加上一条，非常容易内存尖峰无法被回收。

解决方法有
1. 可以设计一个类似 LangGraph 的 DAG 将状态外存，纯化过程态，从而整个内存回收。
2. 或者你用进程架构，每次 turn 为一个进程，直接回收。

但是这两种架构成本就很高，改动起来要点和注意的点非常多，没有那么简洁优雅。

[KonghaYao - 江夏尧 @konghayao]

@mrbleem_eth DSH 没这功能哈，T3Code 才能选 Codex 还是 CC

[KonghaYao - 江夏尧 @konghayao]

@geekbb luna 有 deepseek 快吗

[KonghaYao - 江夏尧 @konghayao]

为啥 subagent 不是进程模型？

1. 难道要重新扫一磁盘获取 settings+skills 吗？还是设计一套进程数据传输方案？
2. MCP 是不是得重开，x2 进程数+双状态存储？
3. subagent resume 怎么办，重新开进程？再走上面一遍？

[KonghaYao - 江夏尧 @konghayao]

@yifanxu_ephai 我们初创AI企业，老板学术圈的，我们负责写整个程序，算法和方向也有支撑