# Agency：构建接近自主的AI编程代理工作流

> 本文介绍srid/agency项目，这是一个将AI编程代理工作流打包为APM包的创新方案，通过/do和/talk等命令实现从研究到PR的全自动流水线。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-16T22:44:56.000Z
- 最近活动: 2026-04-16T22:52:39.766Z
- 热度: 159.9
- 关键词: AI编程代理, 自动化工作流, 代码质量, 软件架构, APM包, Claude Code, 简单性原则, 模块化设计
- 页面链接: https://www.zingnex.cn/forum/thread/agency-ai
- Canonical: https://www.zingnex.cn/forum/thread/agency-ai
- Markdown 来源: ingested_event

---

# Agency：构建接近自主的AI编程代理工作流

在AI辅助编程工具日益普及的今天，开发者们面临着一个共同的挑战：如何在保持控制的同时，让AI代理承担更多重复性工作？srid/agency项目提供了一个优雅的解决方案——将接近自主的编码工作流打包为可复用的APM（Agent Package Manager）包，让AI代理能够独立完成从研究到代码提交的完整流程。

## 什么是Agency？

Agency是一个为编码代理设计的近自主工作流框架，以APM包的形式分发。它定义了一套标准化的命令和流程，使AI代理能够在人类监督下自主完成复杂的开发任务。

项目的核心理念是：将最佳实践编码化为可自动执行的流程，同时保留人类在关键决策点的介入能力。这种"放手但可控"的模式，代表了AI辅助开发的新范式。

## 核心命令：/do 和 /talk

Agency围绕两个主要命令构建：

### /do —— 全自动流水线

这是Agency的旗舰功能。执行/do命令后，AI代理将自动完成以下完整流程：

1. **研究（Research）**：分析需求，探索实现方案
2. **架构评估（Hickey）**：使用Rich Hickey的"Simple Made Easy"框架评估结构简单性
3. **模块分解审查（Lowy）**：基于Juval Lowy的框架检查模块边界是否封装了变化轴
4. **分支创建**：在版本控制中创建功能分支
5. **代码实现**：根据研究结论编写代码
6. **质量检查（Code Police）**：三阶段质量门——规则检查、事实核查、优雅度审查
7. **CI验证**：运行持续集成流程
8. **PR生成（Forge PR）**：编写开发者真正想读的PR标题和描述

整个过程无需人工干预，直到最后的PR审查阶段。

### /talk —— 对话模式

与/do不同，/talk是一个纯对话模式。代理可以讨论想法、探索方案、阅读代码，但不允许修改文件。这适用于需求澄清、架构讨论、代码审查等场景，让开发者在动手编码前充分思考。

## 深度解析：子代理架构

Agency的一个关键设计决策是将复杂任务分解为专门的子代理，而不是在单一对话循环中串行执行。这种架构带来了显著优势：

### Hickey子代理：结构简单性评估

以Rich Hickey的著名演讲"Simple Made Easy"为理论基础，hickey子代理专门负责识别代码中的意外复杂性。它检查：

- 是否存在不必要的耦合（complecting）
- 模块职责是否清晰分离
- 是否有更简单的替代方案

重要的是，hickey作为独立子代理运行，可以与lowy并行执行，而不需要在主对话循环中串行等待。

### Lowy子代理：基于易变性的分解

lowy子代理基于Juval Lowy的《Righting Software》框架（继承自Parnas 1972年的模块化标准），检查模块边界是否封装了变化轴而非仅仅是功能。

核心问题是：当需求变化时，哪些模块需要修改？理想情况下，变化应该被隔离在最小范围的模块内。

### Code Police：三阶段质量门

code-police子代理执行严格的三阶段审查：

1. **规则检查**：对照项目定义的规则清单
2. **事实核查**：寻找静默错误捕获、不合理的回退、一厢情愿的假设和逻辑错误
3. **优雅度审查**：迭代优化代码质量，默认运行3轮

这种分层审查机制确保了代码质量的多维度保障。

### Ralph子代理：测量驱动改进

/ralph命令背后的引擎是一个迭代测量循环：分析可量化指标，找到最大贡献因素，应用针对性变更，重新测量。只有确实改善指标的变更才会被提交。

这种模式适用于性能优化、包大小缩减、复杂度降低等任何可量化的改进目标。

## 安装与配置

Agency通过APM分发，安装过程简洁：

```yaml
# apm.yaml
name: yourproject
version: 1.0.0
type: hybrid

dependencies:
  apm:
    - srid/agency#master
```

或使用uvx：

```bash
uvx --from apm-cli apm install -t claude
```

这会生成.claude/目录，包含agency的命令、技能和钩子，并将apm_modules/添加到.gitignore。

## 项目定制化

Agency的真正威力在于可定制性。通过创建.instructions.md文件，开发者可以定义项目特定的工作流和规则：

### 工作流指令

创建`.apm/instructions/workflow.instructions.md`来定义项目的检查、格式化、测试和CI命令：

```markdown
---
description: Workflow commands for the /do pipeline
applyTo: "**"
---

## Check command
`npm run typecheck` — 快速静态正确性检查

## Format command
`npm run lint:fix`

## Test command
`npm test` — 仅运行与变更代码路径相关的测试

## CI command
`npm run ci` — 通过检查退出码0来验证
```

### 代码警察规则

创建`.apm/instructions/code-police-rules.instructions.md`添加项目特定规则：

```markdown
---
description: Project-specific code-police rules
---

## Code Police Rules

### no-raw-sql
所有数据库访问必须使用查询构建器。迁移之外的代码禁止原始SQL字符串。

### always-use-server-functions
数据获取必须通过服务器函数，禁止从组件直接调用API。
```

### Hickey和Lowy目录扩展

通过创建`.apm/instructions/*.instructions.md`文件并指定`applyTo` glob模式，可以为hickey和lowy添加项目特定的检查模式。APM会自动生成paths范围的规则，Claude Code会在子代理读取匹配文件时自动将其作为系统提醒。

## 设计哲学：简单性与封装变化

Agency的设计深深植根于两个经典软件工程原则：

### Rich Hickey的简单性原则

"Simple Made Easy"区分了简单（simple，单一职责、无纠缠）和容易（easy，熟悉、触手可及）。Agency的hickey检查器专门寻找代码中的"纠缠"（complecting）——将本应分离的概念混在一起。

### Parnas/Lowy的模块化原则

David Parnas 1972年的经典论文提出了信息隐藏作为模块化的关键标准。Juval Lowy在此基础上发展出基于易变性的分解方法：模块边界应该封装变化轴，这样当需求变化时，影响范围被最小化。

Agency将这些理论原则转化为可自动执行的检查，帮助开发者在实践中应用这些经过验证的设计智慧。

## 实际应用场景

Agency特别适合以下场景：

**快速原型开发**：当需要快速验证一个想法时，/do可以自动完成从研究到可运行代码的全过程。

**遗留代码重构**：hickey和lowy检查器能够识别代码中的架构问题，ralph可以测量重构前后的指标改进。

**代码审查辅助**：在提交PR前运行code-police，提前发现潜在问题。

**学习最佳实践**：通过观察Agency的工作流程，开发者可以学习系统化的代码质量评估方法。

## 局限性与注意事项

尽管Agency提供了强大的自动化能力，但开发者应该注意：

- **并非完全自主**：项目描述中明确是"近自主"（near-autonomous），关键决策仍需人类判断
- **需要正确配置**：工作流指令的质量直接影响/do的执行效果
- **适用性有限**：对于高度创造性或探索性的任务，纯自动流程可能不如人机协作有效
- **质量门依赖规则**：code-police的效果取决于规则定义的完整性和准确性

## 总结

srid/agency代表了AI辅助开发的一个重要方向：将专家知识和最佳实践编码化为可自动执行的流程。通过子代理架构、分层质量门和可定制的工作流，它在自动化和可控性之间找到了平衡点。

对于希望提升开发效率、标准化代码质量流程的团队来说，Agency提供了一个值得探索的框架。它不仅是一个工具，更是一种将软件工程原则付诸实践的方法论。