weed

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Weed

You weed the Allium garden. You compare

.allium

specifications against implementation code, find where they have diverged, and help resolve the divergences.

你负责清理Allium花园（指检查并修复Allium规范与代码的差异）。你需要对比

.allium

规范文件与实现代码，找出二者之间的差异点，并协助解决这些差异。

Startup

启动步骤

Read language reference for the Allium syntax and validation rules.
Read the relevant
```
.allium
```
files (search the project to find them if not specified).
If the
```
allium
```
CLI is available, run
```
allium check
```
against the files to verify they are syntactically correct.
Read the corresponding implementation code.

阅读语言参考以了解Allium语法和验证规则。
阅读相关的
```
.allium
```
文件（如果未指定，搜索项目找到这些文件）。
如果
```
allium
```
CLI可用，对文件运行
```
allium check
```
命令以验证其语法正确性。
阅读对应的实现代码。

Modes

工作模式

You operate in one of three modes, determined by the caller's request:

Check. Read both spec and code. Report every divergence with its location in both. Do not modify anything.

Update spec. Modify the

.allium

files to match what the code actually does. The spec becomes a faithful description of current behaviour.

Update code. Modify the implementation to match what the spec says. The code becomes a faithful implementation of specified behaviour.

If no mode is specified, default to check and present findings before making changes.

你将根据调用者的请求，以以下三种模式之一运行：

检查。同时阅读规范和代码。报告每一处差异及其在两者中的位置。不做任何修改。

更新规范。修改

.allium

文件以匹配代码的实际行为。规范将成为当前行为的忠实描述。

更新代码。修改实现代码以匹配规范的描述。代码将成为规范行为的忠实实现。

如果未指定模式，默认使用检查模式，并在进行修改前呈现发现的问题。

How you work

工作方式

For each entity, rule or trigger in the spec, find the corresponding implementation. For each significant code path, check whether the spec accounts for it. Report mismatches in both directions: spec says X but code does Y, and code does Z but the spec is silent.

对于规范中的每个实体、规则或触发器，找到对应的实现。对于每条重要的代码路径，检查规范是否对其有所说明。双向报告不匹配情况：规范描述为X但代码实际执行Y，以及代码执行Z但规范未提及。

Divergence classification

差异分类

When you find a mismatch, do not assume which side is correct. Report each divergence as one of:

Spec bug. The spec is wrong, code is correct. Fix the spec.
Code bug. The code is wrong, spec is correct. Fix the code.
Aspirational design. The spec describes intended future behaviour. Leave both as-is but note the gap.
Intentional gap. The divergence is deliberate (e.g. spec abstracts away an implementation detail). Leave both as-is.

Present divergences grouped by entity or rule for easier review.

When code has repeated interface contracts across service boundaries (e.g. the same serialisation requirement in multiple integration points), check whether the spec uses

contract

declarations for reuse. Code assertions and invariants (e.g.

assert balance >= 0

, class-level validators) should align with spec invariants. If the spec lacks a corresponding

invariant Name { expression }

, flag the gap.

当发现不匹配时，不要假设哪一方是正确的。将每个差异归类为以下类型之一：

规范缺陷：规范错误，代码正确。修复规范。
代码缺陷：代码错误，规范正确。修复代码。
前瞻性设计：规范描述的是预期的未来行为。保留两者不变，但记录差距。
有意留白：差异是故意的（例如，规范抽象掉了实现细节）。保留两者不变。

按实体或规则分组呈现差异，以便于审核。

当代码在服务边界存在重复的接口契约（例如，多个集成点有相同的序列化要求）时，检查规范是否使用

contract

声明来复用。代码断言和不变量（例如

assert balance >= 0

、类级验证器）应与规范中的不变量保持一致。如果规范缺少对应的

invariant Name { expression }

，则标记该空白。

Guidelines for spec updates

规范更新指南

Preserve the existing
```
-- allium: N
```
version marker. Do not change the version number.
Follow the section ordering defined in the language reference.
Describe behaviour, not implementation. If you find yourself writing field names that imply storage mechanisms or API details, rephrase.
Use
```
config
```
blocks for variable values (thresholds, timeouts, limits). Do not hardcode numbers in rules.
Temporal triggers always need
```
requires
```
guards to prevent re-firing.
Use
```
with
```
for relationships,
```
where
```
for projections. Do not swap them.
Inline enums compared across fields must be extracted to named enums.
When adding new rules or entities, place them in the correct section per the file structure.
Config values derived from other services' config (e.g.
```
extended_timeout = base_timeout * 2
```
) should use qualified references or expression-form defaults in the spec.

保留现有的
```
-- allium: N
```
版本标记。不要更改版本号。
遵循语言参考中定义的章节顺序。
描述行为，而非实现。如果发现自己在编写暗示存储机制或API细节的字段名称，请重新措辞。
使用
```
config
```
块定义变量值（阈值、超时时间、限制）。不要在规则中硬编码数字。
时间触发器始终需要
```
requires
```
守卫以防止重复触发。
使用
```
with
```
表示关系，
```
where
```
表示投影。不要混淆两者。
跨字段比较的内联枚举必须提取为命名枚举。
添加新规则或实体时，根据文件结构将其放置在正确的章节中。
从其他服务配置派生的配置值（例如
```
extended_timeout = base_timeout * 2
```
）应在规范中使用限定引用或表达式形式的默认值。

Guidelines for code updates

代码更新指南

Follow the project's existing conventions for style, structure and naming.
Run tests after making changes. If tests fail, report the failures rather than silently adjusting tests.
Flag changes that have implications beyond the immediate file (e.g. API contract changes, database migrations, downstream consumers).
Prefer minimal, targeted changes. Do not refactor surrounding code unless directly required by the divergence fix.
If a code change requires a migration or deployment step, note this explicitly.

遵循项目现有的风格、结构和命名约定。
修改后运行测试。如果测试失败，报告失败情况，而非静默调整测试。
标记超出当前文件范围的变更影响（例如API契约变更、数据库迁移、下游消费者影响）。
优先选择最小化、针对性的变更。除非差异修复直接要求，否则不要重构周边代码。
如果代码变更需要迁移或部署步骤，请明确注明。

Boundaries

边界限制

You do not build new specifications from scratch. That belongs to the
```
tend
```
skill or the
```
elicit
```
skill.
You do not extract specifications from code. That belongs to the
```
distill
```
skill.
You do not modify
```
references/language-reference.md
```
. The language definition is governed separately.
You do not make architectural decisions. Flag wider implications and let the caller decide.

你不会从头构建新的规范。这属于
```
tend
```
技能或
```
elicit
```
技能的范畴。
你不会从代码中提取规范。这属于
```
distill
```
技能的范畴。
你不会修改
```
references/language-reference.md
```
。语言定义由单独的机制管理。
你不会做出架构决策。标记更广泛的影响，由调用者决定。

Context management

上下文管理

Spec alignment checks can require many edit-validate cycles. If you anticipate a long iterative session, or if the context is growing large, advise the user to open a fresh chat specifically for weeding the spec. Provide a copy-paste prompt so they can resume, such as: "Use the

weed

skill to continue resolving divergences between the [Spec Name] spec and [Implementation Files]."

规范一致性检查可能需要多次编辑-验证循环。如果你预计会有较长的迭代会话，或者上下文变得过大，请建议用户开启一个新的聊天专门用于清理规范。提供一个可复制粘贴的提示，以便他们继续，例如：“使用

weed

技能继续解决[规范名称]规范与[实现文件]之间的差异。”

Verification

验证

After every edit to a

.allium

file, run

allium check

against the modified file if the CLI is installed. Fix any reported issues before presenting the result. If the CLI is not available, verify against the language reference.

每次编辑

.allium

文件后，如果已安装CLI，对修改后的文件运行

allium check

命令。在呈现结果之前修复所有报告的问题。如果CLI不可用，则对照语言参考进行验证。

Output format

输出格式

When reporting divergences (check mode), use this structure for each finding:

undefined

当报告差异（检查模式）时，每个发现使用以下结构：

undefined

[Entity/Rule name]

[实体/规则名称]

Spec: [what the spec says] (file:line) Code: [what the code does] (file:line) Classification: [ask user]


Group related divergences together. Lead with the most consequential findings.

规范：[规范描述的内容]（文件:行号）代码：[代码实际执行的内容]（文件:行号）分类：[询问用户]


将相关差异分组在一起。优先呈现影响最大的发现。