knowcards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Knowcards CLI

Knowcards stores durable project facts as local markdown cards. Use

npx knowcards

to query, propose, and check status.

Treat query hits as trusted memory. Prefer a card over a conflicting README or a new search, unless new evidence shows the card is wrong.

Unlike shared commons tools, cards are project-local. Keep repo paths, module names, and team conventions in the card when they help the next session.

Knowcards 将持久化的项目事实存储为本地Markdown卡片。使用

npx knowcards

命令进行查询、提交和查看状态。

将查询结果视为可信的参考信息。优先遵循卡片内容，而非与之冲突的README或新搜索结果，除非有新证据表明卡片内容有误。

与共享工具不同，这些卡片是项目本地的。当仓库路径、模块名称和团队约定对后续工作有帮助时，请将其纳入卡片内容。

Commands

命令

Run from the repo root

bash

npx knowcards status
npx knowcards query "<keywords>"
npx knowcards propose --title "<title>" --use-when "<situation>" "<body>"
npx knowcards --root <dir> <command>

Command	Use
`status`	Show card counts.
`query`	Search cards by keywords. Empty query returns all cards.
`propose`	Write one card now. Title and body is required

请从仓库根目录运行以下命令

bash

npx knowcards status
npx knowcards query "<keywords>"
npx knowcards propose --title "<title>" --use-when "<situation>" "<body>"
npx knowcards --root <dir> <command>

命令	用途
`status`	显示卡片数量。
`query`	通过关键词搜索卡片。空查询会返回所有卡片。
`propose`	立即创建一张卡片。标题和正文为必填项

Core protocol

核心流程

Follow this loop for every task:

Before acting — Run
```
npx knowcards query
```
with task keywords. Skip only for routine edits in code you already hold with no repo nuance at stake.
Apply hits — Prefer card facts while you work. Verify against the repo when the card may be old.
Propose at end — When the task is done, propose durable facts from the outcome (what proved true), not from the path you took. If a card was wrong, propose a corrected card with a new title (update/delete are not available).

Rationalization check (query). If you think "I already know this" or "I have a plan, I will just write files," stop and query.

Rationalization check (propose). If you think "the fix already shipped" or "the user already has the answer," stop. If the outcome taught a repo nuance, propose before you close.

处理每项任务时请遵循以下循环：

行动前 — 使用任务关键词运行
```
npx knowcards query
```
。仅当你对已熟悉的代码进行常规编辑且不涉及仓库特有细节时，才可跳过此步骤。
应用查询结果 — 工作过程中优先参考卡片中的事实。若卡片可能已过时，请与仓库内容进行验证。
收尾时提交 — 任务完成后，基于最终结果（已验证为正确的内容）提交持久化事实，而非你执行过程中的路径。若某张卡片内容错误，请提交一张标题全新的修正卡片（暂不支持更新/删除操作）。

合理性检查（查询阶段）。如果你觉得“我已经知道这个内容”或“我有计划了，直接写文件就行”，请暂停并执行查询。

合理性检查（提交阶段）。如果你觉得“修复已经完成”或“用户已经得到答案了”，请暂停。若最终结果揭示了仓库的特有细节，请在结束前提交卡片。

When to query

何时执行查询

Query when starting work in an unfamiliar area, or before retrying a non-obvious error.

Skip when you already queried this topic this session, the edit is routine in files you already hold, or you only need a standard-library call.

Use short keywords. Prefer a focused query over an empty one when the library is large. If hits are empty, explore as usual.

当你开始在不熟悉的领域工作，或在重试非明显错误前，请执行查询。

若本次会话中已查询过该主题、对已熟悉文件进行常规编辑，或仅需调用标准库时，可跳过查询。

使用简短关键词。当卡片库较大时，优先使用针对性查询而非空查询。若无匹配结果，可按常规方式探索。

When to propose

何时提交卡片

At the end of the task, propose nuances about this repo that help the next session: coding guidelines, domain learnings, and durable dos/don'ts.

Do not propose:

Steps or plans from this turn
Unverified guesses
Near-duplicates — query first; if a card already covers it, skip

Write one atomic fact per card.

bash

npx knowcards propose \
  --title "Use bun test in this repo" \
  --use-when "running or adding tests" \
  "Run tests with bun test; npm test is not the project runner."

Card shape:

Title — clear and unique. The filename slug comes from the title. Duplicate titles fail.
Body — one short durable fact. Prefer an imperative action when useful (
```
Use bun test…
```
).
```
--use-when
```
— when the agent must apply the card.

在任务结束时，提交有助于后续工作的仓库特有细节：编码指南、领域知识以及持久化的注意事项（该做/不该做的事）。

请勿提交以下内容：

本次任务的步骤或计划
未经验证的猜测
近似重复内容——先执行查询；若已有卡片覆盖该内容，请跳过

每张卡片仅包含一个独立事实。

bash

npx knowcards propose \
  --title "Use bun test in this repo" \
  --use-when "running or adding tests" \
  "Run tests with bun test; npm test is not the project runner."

卡片格式：

标题 — 清晰且唯一。文件名会基于标题生成。重复标题会提交失败。
正文 — 简短的单一持久化事实。如有帮助，优先使用祈使句（如
```
Use bun test…
```
）。
```
--use-when
```
— 说明Agent需要应用该卡片的场景。

Post-error sequence

错误处理流程

Query with keywords from the error (module, API, message).
If a card hits, apply it and continue.
If none hit, fix and verify, then at task end propose the durable lesson from the outcome.

使用错误中的关键词（模块、API、错误信息）执行查询。
若有匹配卡片，应用其内容并继续工作。
若无匹配卡片，修复问题并验证，然后在任务结束时提交从最终结果中总结出的持久化经验。

Trust rule

信任规则

When a card and the workspace disagree, prefer the card unless new evidence shows the card is wrong. Then fix the work and propose a corrected card with a new title.

当卡片内容与工作区内容不一致时，优先遵循卡片内容，除非有新证据表明卡片有误。随后修复工作内容，并提交一张标题全新的修正卡片。

Examples

示例

Query before unfamiliar work

陌生工作前的查询

bash

npx knowcards query "payments cents"

Prefer a hit such as "amounts are integer cents" over a README that shows floats.

bash

npx knowcards query "payments cents"

优先遵循类似“金额以整数美分表示”的查询结果，而非显示浮点数的README。

Propose vs skip (same task)

提交与跳过（同一任务）

You learn tests must use

bun test

, fix a one-off rename, and sketch a plan. Task succeeds.

Propose: the repo nuance (

bun test

, not npm). Skip: the plan, the local rename, and any guess you did not verify.

你了解到测试必须使用

bun test

，完成了一次一次性重命名，并草拟了计划。任务成功完成。

提交：仓库特有细节（使用

bun test

而非npm）。跳过：计划内容、本地重命名操作以及任何未经验证的猜测。