astkit-tooling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

astkit tooling

astkit 工具集

Use

astkit

for token-efficient repository exploration and structural edits in TS/JS projects. Keep scope narrow first, expand only when evidence is insufficient.

在TS/JS项目中，使用

astkit

进行高效的仓库探索与结构化编辑。先限定窄范围，仅当现有证据不足时再扩大范围。

Quick Start

快速开始

Confirm tool availability.

```
astkit --help
```
or
```
npx astkit --help
```
or
```
bunx astkit --help
```

Start with one focused operation.

```
astkit nav declarations <file>
```

astkit nav definition <file:line:character>

astkit nav references <file:line:character>

astkit search '<pattern>' <scope> --json

astkit patch --dry-run '<patch-document>' <scope>

astkit code-rank <scope> --limit 25 --json

Expand scope only if needed.

确认工具可用。

```
astkit --help
```
或
```
npx astkit --help
```
或
```
bunx astkit --help
```

从一项聚焦的操作开始。

```
astkit nav declarations <file>
```

astkit nav definition <file:line:character>

astkit nav references <file:line:character>

astkit search '<pattern>' <scope> --json

astkit patch --dry-run '<patch-document>' <scope>

astkit code-rank <scope> --limit 25 --json

仅在需要时扩大范围。

Working Workflow

工作流程

Map contracts before implementation details.

Use
```
nav declarations
```
and
```
nav definition
```
first.
Treat signatures/docs as intended contracts until contradicted by evidence.

Clarify behavior from usage.

Use
```
nav references
```
to inspect representative callsites.
Prefer usage patterns over deep source reading for initial understanding.

Estimate blast radius before edits.

Use
```
code-rank
```
and references to identify high-impact symbols.
Prefer localized changes when task scope is localized.

Rewrite with structural tools.

Use
```
search
```
to find candidate shapes.
Use
```
patch --dry-run
```
before writing changes.
Use
```
patch --interactive
```
for high-risk or broad rewrites.

Re-check and validate.

Re-run focused
```
search
```
/
```
nav references
```
on touched symbols.
Validate with
```
tsc
```
and relevant tests when available.

先梳理契约，再关注实现细节。

优先使用
```
nav declarations
```
和
```
nav definition
```
。
在有证据反驳之前，将签名/文档视为既定契约。

通过用法明确行为。

使用
```
nav references
```
查看有代表性的调用位点。
初始理解时，优先参考使用模式而非深入阅读源码。

编辑前评估影响范围。

使用
```
code-rank
```
和引用信息识别高影响符号。
当任务范围局限时，优先选择本地化修改。

使用结构化工具进行重写。

使用
```
search
```
查找符合特征的候选对象。
在实际修改前使用
```
patch --dry-run
```
。
对于高风险或大范围重写，使用
```
patch --interactive
```
。

重新检查与验证。

对修改过的符号重新运行聚焦的
```
search
```
/
```
nav references
```
。
若有可用工具，使用
```
tsc
```
和相关测试进行验证。

Safe Rewrite Workflow

安全重写流程

Find candidate sites.

astkit search '<pattern>' <scope> --json

Preview rewrite.

astkit patch --dry-run '<patch-document>' <scope>

Apply rewrite.

```
astkit patch '<patch-document>' <scope>
```
Use
```
--interactive
```
for high-risk or broad edits.

Re-check surfaced contracts.

Re-run focused
```
search
```
queries and
```
nav references
```
on touched symbols.

Validate with compiler and tests.

Run
```
tsc
```
diagnostics.
Run focused tests for touched behavior.

查找候选位点。

astkit search '<pattern>' <scope> --json

预览重写效果。

astkit patch --dry-run '<patch-document>' <scope>

应用重写。

```
astkit patch '<patch-document>' <scope>
```
对于高风险或大范围编辑，使用
```
--interactive
```
。

重新检查涉及的契约。

对修改过的符号重新运行聚焦的
```
search
```
查询和
```
nav references
```
。

用编译器和测试验证。

运行
```
tsc
```
诊断。
对修改的行为运行针对性测试。

Reporting Contract

报告规范

When reporting findings, include:

system boundaries and entry points
invariants/contracts with explicit status (
```
observed
```
vs
```
inferred
```
)
definition/reference flow summary
change hotspots/dependency hubs
suggested edits with blast-radius notes
validation status and remaining gaps

Keep output concise and include file paths/spans where possible.

提交结果报告时，需包含：

系统边界与入口点
不变量/契约及明确状态（
```
observed
```
或
```
inferred
```
）
定义/引用流摘要
变更热点/依赖枢纽
带影响范围说明的建议修改
验证状态与剩余缺口

保持输出简洁，并尽可能包含文件路径/位置信息。

Guardrails

注意事项

Structural similarity does not imply behavioral equivalence.
Structural rewrites reduce accidental matches but do not guarantee correctness.
Reference ranking approximates impact, not runtime criticality.
No matches do not prove absence of behavior.
Do not use this skill as a substitute for compiler diagnostics or tests.

结构相似并不意味着行为等价。
结构化重写减少意外匹配，但不保证正确性。
引用排名仅近似影响程度，而非运行时关键程度。
无匹配结果不代表不存在该行为。
请勿将此工具替代编译器诊断或测试。

Common Failure Modes

常见失败模式

Too many matches: narrow scope, add delimiters, add regex constraints.
No matches: verify pattern shape, scope, and
```
--no-isomorphisms
```
usage.
Rewrite too broad: switch to
```
--interactive
```
and re-run dry-run first.
Unclear impact: inspect
```
nav references
```
and
```
code-rank
```
before applying.

匹配结果过多：缩小范围、添加分隔符、增加正则约束。
无匹配结果：验证模式结构、范围及
```
--no-isomorphisms
```
的使用。
重写范围过宽：切换到
```
--interactive
```
模式，并先重新运行预演。
影响不明确：在应用前检查
```
nav references
```
和
```
code-rank
```
结果。

References

参考资料

```
./references/cognitive-model.md
```
```
./references/non-goals.md
```

```
./references/cognitive-model.md
```
```
./references/non-goals.md
```