byterover

ByteRover — 持久化项目记忆

ByteRover 将项目知识保存为确定性的上下文树。你是大脑；引擎绝不会调用 LLM。 你负责推理，然后通过 Bash 工具运行捆绑的确定性脚本，以检索或保存知识。

铁律

1. 思考之前先查询。 开始任何非简单任务时，先检索项目已有的知识，以免重新推导或与之矛盾。
2. 实现之后再整理。 完成值得记住的内容（决策、易踩的坑、模式）后，将其写回，让下一个会话也能继承。

记忆存放位置

引擎会根据你的工作目录解析正确的上下文树。不要计算、查找或覆盖存储路径。 在项目内（任意子目录均可）运行命令，就会自动找到正确的树——解析器和注册表都属于引擎内部机制。

语言

使用与用户输入相同的语言。 使用用户对话所用的语言编写可读内容，包括 <bv-*> 元素的正文、列表项，以及 <bv-topic> 上的 title / summary 属性。不需要设置，也没有标志；你应像回复时一样，根据对话推断语言。

架构保持英文。 为确保工具兼容性，标签名（<bv-fact>，不能翻译标签）、属性名（subject、category、severity）、枚举值（category="project"、subject="visa_required"）以及 path 属性都必须保留为英文。代码片段和标识符也必须原样保留。

具体示例（越南语对话）：path="travel/vietnam_visa" 和 subject="visa_required" category="project" 保持英文，而 title="Yêu cầu visa Việt Nam" 和 <bv-fact> 正文（Người Mỹ cần visa để vào Việt Nam.）使用越南语。中文、日语、韩语、俄语、阿拉伯语等也遵循同一规则。

命令

在项目内（任意子目录均可）运行。主题以 <bv-*> HTML 格式存储。空间（包括默认空间）通过 ByteRover 桌面应用创建——Agent 不会创建它们。

需求	命令
检索	node scripts/query.mjs "<question>" --limit 5
保存（包含多个元素的丰富主题）	node scripts/record.mjs "<topic-path>" --html '<bv-topic …>…</bv-topic>' — 请参阅下方“编写丰富主题”中的完整示例；不要根据此行自行推断格式
保存（简单的单事实主题）	node scripts/record.mjs "<topic-path>" --title "T" --summary "S" --keywords a,b --body "..."
一次调用保存多个主题	node scripts/record.mjs --batch --input <ndjson-file>（每行一条 JSON 规范：{"path":"...","html":"<bv-topic …>…</bv-topic>","overwrite"?:true}；整个批次只进行一次身份验证和一次清单/索引重建——比逐条记录 N 个主题快得多；每行的失败会报告在 failed[] 中，不会中止运行）

**必需的 <bv-topic> 属性：**主题根节点上必须存在非空的 path 和 title，否则写入器会拒绝该调用。<bv-topic> 上的 path 应与传递给 record.mjs 的位置参数 <topic-path> 一致。完整属性规范请参阅 vocabulary.md。 | 读取 | node scripts/brv.mjs read "<topic-path>.html" [--raw]（使用 --raw 可逐字节获取磁盘上的 HTML——通过 record --html 往返处理时必须使用，因为 elements[].text 会扁平化内部的 <ul>/<li>/<strong> 格式） | | 列出 | node scripts/brv.mjs list | | 重建清单和索引 | node scripts/manifest.mjs | | 检测整合机会 | node scripts/dream.mjs --mode merge\|link\|prune\|synthesize（仅提出建议——绝不执行） | | 将一个主题并入另一个主题 | node scripts/merge.mjs <survivor> <loser> [--title "…"] [--summary "…"] [--tags a,b] [--keywords a,b] [--reason "…"] [--related @x.html,@y.html]（使用 --title 为保留的主题指定能体现合并后范围的新标题；否则，即使合并后的内容范围更广，保留主题仍使用原有标题） | | 移除冗余主题 | node scripts/prune.mjs <topic-path>...（可变参数，原子操作——首次失败时中止，并提供部分执行报告） | | 将多个主题合并为一个新主题 | node scripts/synthesize.mjs <new-path> --html '<bv-topic …>…</bv-topic>' --absorb a.html,b.html,c.html | | 在当前空间内重命名、移动或更改主题的父级 | node scripts/move.mjs <topic-path> --to-path <new-path>（原子操作——将同级主题的 related= 引用改写为新路径；信号 sidecar 会一并迁移；涵盖重命名、移至新父级、深层更改父级及其组合操作） | | 添加或移除两个主题之间的 related= 交叉链接 | node scripts/brv.mjs link "<a>" "<b>" [--bidirectional] [--remove]（以保留字节的方式原子编辑 <bv-topic related="…"> 属性——请使用此命令，而不要手动编辑起始标签，因为摘要中含有 > 字符时手动编辑不安全；幂等——重复建立链接不会产生变化；拒绝添加指向不存在主题的引用（否则会产生悬空引用）——但 --remove 允许目标缺失，以便清理现有的悬空引用） | | 将主题移至其他空间 | node scripts/move.mjs <topic-path> --from-space <name> --to-space <name>（重建两个空间的清单和索引；报告源空间中现已悬空的同级 related= 引用） | | 迁移旧版 Markdown | node scripts/migrate.mjs [--dry-run] | | 将可自托管的 v3 VPS 迁移至 v4（完整引导流程） | 按照 migrate-v3-to-v4.md 中的步骤操作 | | 验证身份／登录 ByteRover | node scripts/auth.mjs — 立即返回；用户在浏览器中批准后，再运行 auth.mjs status；请参阅 使用 ByteRover 验证身份 | | 检查是否已登录（本地检查，不访问网络） | node scripts/auth.mjs whoami — 输出 { ok, authed, providerKind }（表示本地存在凭据；不检查凭据在服务器端是否有效） | | 退出 ByteRover | node scripts/logout.mjs | | 查看此文件夹使用的空间 | node scripts/space.mjs current | | 列出空间（按 team_name 分组） | node scripts/space.mjs list | | 将此文件夹绑定到某个空间 | node scripts/space.mjs bind "<name>" |

若要删除主题，请将请求转达给用户——删除操作需通过 ByteRover 桌面应用完成。

每条命令都会输出 JSON 结果。若结果为 { "ok": false, ... }，请阅读 troubleshooting.md。

引用检索到的记忆

如果 query 的回答实质上依据了返回的命中结果，请在回复后附上查询信封中的 citation_block，让用户了解并点击查看所用内容。引擎会预先格式化此区块；你只需判断是否附上，无需格式化。

当查询信封中的 should_cite: true，且你的回答确实使用了检索到的记忆时：

1. 在回答后添加一个空行。
2. 逐字逐字符输出 citation_block 字符串，包括每个标题外层的 […](…) Markdown 链接、存在时缩进的 "snippet" 行，以及存在时的 Updated by <agent> · <relative> 尾行。引擎面向的每个宿主（Codex CLI、Claude Code CLI、Claude Code Desktop）都会将带链接的标题显示为可点击的内联链接。
3. 不要重新格式化、改述引用内容，也不要添加由 Agent 生成的相关性评分。用户会根据标题判断相关性。
4. 不要去掉 Markdown 链接。 引擎有意输出 - [Title · Recalled N×](http://…)——将其改成纯标题并把 URL 放到另一行，会破坏隐藏长 URL、仅显示可点击文本的格式。摘要和更新者行也遵循相同规则：严格保留引擎输出的缩进，绝不要将它们合并到标题行，也不要去掉行首空格。

当 should_cite 为 false，或你并未实际使用返回的命中结果来作答，或用户要求不提供来源时——完全跳过此区块。 引擎会有意抑制低置信度的检索结果；不要自行判断并在正文中展示。

最终回复格式示例（📚 … 区块由引擎提供，请逐字输出）：

ATM: Er Rak Error is a 2012 Thai romantic comedy by Mez Tharatorn …

📚 From ByteRover:
- [ATM: Er Rak Error (2012 Thai film) (fact)  ·  Recalled 14×](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/atm_er_rak_error.html#bve-a1b2c3d4)
    "matched-context preview that explains why this hit ranked here"
    Updated by claude · 3d ago
- [Pee Mak Phra Khanong (2013) (highlights)](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/pee_mak_phra_khanong.html#bve-e5f6g7h8,k1m2n3p4)

使用 ByteRover 进行身份验证

当用户希望为此工作区进行身份验证 / 登录 / 登录账户 / 连接 / 关联 ByteRover（或 ByteRover 报告会话已过期）时，运行：

node scripts/auth.mjs

此命令会立即返回 { "ok": true, "pending": true, "verifyUrl": …, "userCode": …, "expiresInS": … }，同时后台进程会等待用户批准。将 verifyUrl（和代码）原样转发给用户，告知代码的有效时长（expiresInS，通常为几分钟），并请用户在浏览器中批准后回来告知“已批准”。结束当前轮次——等待期间不要轮询或重新运行命令。

用户返回后，使用以下命令确认：

node scripts/auth.mjs status

• { "state": "approved" } → 已连接；告知用户。
• { "state": "pending" } → 尚未完成——请用户完成浏览器中的步骤（结果会再次包含 verifyUrl），并再次说明。
• { "state": "expired" } → 代码已失效；重新运行 node scripts/auth.mjs 获取新代码并转发给用户。
• { "state": "denied" } → 用户已拒绝；停止并告知用户。

当身份验证流程仍在等待时，重新运行 auth.mjs 是安全的——它会返回相同代码（"reused": true），绝不会生成另一个竞争代码。聊天中不会粘贴任何密钥——只会提供短代码。要退出登录 / 注销：

node scripts/logout.mjs

仅在非交互式 / CI 环境中，可通过文件提供 API 密钥（绝不要直接写在对话中）：node scripts/auth.mjs --key-file <path>。还有一个会在前台阻塞并等待批准的变体（用于脚本，不要用于对话）：node scripts/auth.mjs --wait。

无需进行身份验证——所有命令都可在未登录时使用。请参阅 sync.md，了解身份验证后可启用的功能；如果 auth.mjs 返回 { "ok": false }，请参阅 troubleshooting.md。

编写丰富主题

主题会渲染为 四个部分，编写时应考虑这一结构。每个 <bv-*> 元素都属于一个部分；渲染器会忽略各部分内的顺序，但你应按部分顺序输出，以保持源内容易读。

部分	元素	内容
## Reason（原因）	<bv-reason>	此项整理的“原因”，用 1–2 句话说明。几乎总是应包含此项。
## Raw Concept（原始概念）	<bv-task>、<bv-changes>、<bv-files>、<bv-flow>、<bv-timestamp>、<bv-author>、<bv-pattern>	概念本身：主题、变更、相关文件、流程、日期、作者、正则表达式模式。
## Narrative（说明）	<bv-structure>、<bv-dependencies>、<bv-highlights>、<bv-rule>、<bv-examples>、<bv-diagram>	结构文档、依赖项、重点、项目规则、实例演示、保留的图表。
## Facts（提取的数据）	<bv-fact>	离散、可查询的事实——每个元素包含一条。不要用来堆放属于 Narrative 的内容。
Runbook（任意部分）	<bv-decision>、<bv-bug> + <bv-fix>（同级元素）	独立的运行手册记录。

每个主题都必须包含：

1. 一个 <bv-reason>，说明此次整理的原因（没有说明捕获内容的背景，主题就没有用处）。
2. 一个 <bv-task>，描述主题内容（一句话）；如果“任务”不适用，则使用 <h1> + 介绍性 <p>。
3. 至少一个除 task 之外的 Narrative 或 Raw Concept 元素： <bv-changes> / <bv-files> / <bv-flow> / <bv-structure> / <bv-dependencies> / <bv-highlights> / <bv-decision> / <bv-bug> / <bv-fix>。只有一组 <bv-fact> 同级元素的主题只是占位内容，不算主题。
4. 如果内容有参考日期，则添加 ISO 8601 格式的 <bv-timestamp>。
5. 对每个提取的事实，使用 <bv-fact subject="snake_case" category="…" value="…">标准陈述</bv-fact>：subject 使用 snake_case，category 取值为 personal / project / preference / convention / team / environment / other 之一，value 填写提取后的形式，而 正文必须是自然语言的标准陈述（不能是标签）。

示例演示——研究/档案类主题

Agent 应按以下形式编写。复制此框架并填写各项；不要自行改成更扁平的结构：

node scripts/record.mjs "movies/atm_er_rak_error" --html '
<bv-topic path="movies/atm_er_rak_error"
          title="ATM: Er Rak Error (2012 Thai film)"
          summary="GTH 2012 romantic comedy by Mez Tharatorn — secretly-dating bank employees bet their jobs on recovering money from a malfunctioning ATM."
          keywords="atm_er_rak_error,gth,thai_romcom,mez_tharatorn,2012"
          tags="film,thai,gth,romcom"
          related="@movies/pee_mak_phra_khanong.html">

  <bv-reason>
    Anchor topic for cross-references between Thai GTH romcoms; documents
    the studio box-office record holder before Pee Mak (2013).
  </bv-reason>

  <bv-task>Profile of ATM: Er Rak Error (2012) — credits, plot, awards, legacy.</bv-task>

  <bv-timestamp>2012-01-19</bv-timestamp>

  <bv-highlights>
    Premise: a bank no-fraternization policy forces a secret 5-year couple
    into a winner-keeps-the-job bet over money from a glitching ATM.
    Was GTH biggest hit until Pee Mak (2013) topped it.
  </bv-highlights>

  <bv-structure>
    <p>Credits:</p>
    <ul>
      <li><strong>Director:</strong> Mez Tharatorn</li>
      <li><strong>Writers:</strong> Mez Tharatorn, Aummaraporn Phandintong</li>
      <li><strong>Studio:</strong> GTH (GMM Tai Hub)</li>
    </ul>
    <p>Lead cast:</p>
    <ul>
      <li><strong>Sua:</strong> Ter Chantavit Dhanasevi</li>
      <li><strong>Jib:</strong> Ice Preechaya Pongthananikorn</li>
    </ul>
  </bv-structure>

  <bv-flow>
    Sua and Jib are bank staff who dated secretly for 5 years under the
    bank no-fraternization policy. An ATM glitches and dispenses 130,000
    baht. They bet: whoever recovers the money keeps their job. The
    sequence escalates into a chaotic showdown involving manager Pakorn,
    Sergeant Sam, and Sam pet crocodile Jack.
  </bv-flow>

  <bv-fact subject="release_date" category="project" value="2012-01-19">
    The film was released theatrically in Thailand on January 19, 2012.
  </bv-fact>

  <bv-fact subject="runtime_minutes" category="project" value="123">
    The film runs 123 minutes.
  </bv-fact>

  <bv-fact subject="box_office" category="project" value="150.11 million baht">
    The film grossed 150.11 million baht, reaching Thailand 7th highest-
    grossing film within four weeks of release.
  </bv-fact>

  <bv-fact subject="record_vs_pee_mak" category="project" value="GTH highest-grossing film until Pee Mak (2013)">
    ATM was GTH/GMM Tai Hub highest-grossing film until Pee Mak surpassed it in 2013.
  </bv-fact>

  <bv-changes>
    <li>2013-11-30 to 2014-02-08: TV sequel ATM 2: Koo ver Error Er Rak aired (21 episodes, One 31).</li>
    <li>Chinese-language remake released as Welcome to the Beartown.</li>
  </bv-changes>

</bv-topic>'

注意各项承载的内容：

• <bv-reason> 承载此次整理的原因。 这是最常见的编写疏漏——不要跳过。
• <bv-task> + <bv-timestamp> 承载内容和时间。
• <bv-highlights> + <bv-flow> 承载方式（说明和流程）。
• <bv-structure> 承载分组列表，例如演员阵容/演职员名单/文件布局——不要堆放一组 <bv-fact> 同级元素。<bv-fact> 应用于离散、可查询的声明（上映日期、时长、票房、奖项）。

输出约定（硬性规则）

此架构较为宽松——写入器会静默接受违规内容——但忽略这些规则的输出排名较低，可读性也较差：

• 所有属性值都必须用双引号括起来。 不要使用单引号。
• 所有属性名称都必须使用小写。
• 路径段必须使用带下划线的 snake_case： movies/atm_er_rak_error，而不是 movies/atm-er-rak-error（连字符）。
• related= 指向文件时使用 @path.html，指向文件夹/领域时使用不带扩展名的 @path。必须添加 @ 前缀。
• 不要用代码围栏包裹。 --html 参数必须是裸 HTML——首字符为 <，末尾字符为 </bv-topic>。不要使用 ``` 或 ```html。
• 不要在 <bv-topic> 上设置 createdat、updatedat、id、importance、maturity 或 recency。写入器系统会为前三项添加戳记；后三项是由 LLM 编写器之外的运行时信号。
• 不要使用 <bv-*> 这 19 种元素以外的自定义元素，也不要使用各元素文档架构之外的属性。

敏感性 — 标记你打算分享的事实

一个主题可以通过三种视图分享：完整（全部内容）、已脱敏 （仅包含 <bv-fact disclosure="public"> 和结构性说明）以及 元数据（不透明的目录句柄，不含内容）。给你打算分享的事实标记 disclosure="public"；否则，该事实默认受限，并会从已脱敏视图中剔除。

撰写时请遵循以下三条规则：

• <bv-fact> 是唯一用于逐项限制内容的单元。 主题的 title 和所有说明文字（位于 <bv-structure>、<p>、<bv-flow>、 <bv-highlights> 等元素内）都按约定公开，在已脱敏视图中会原样保留。 切勿在标题或说明文字中放入机密；应将其移入 <bv-fact>（这样便可 默认设为受限）。
• 缺少或拼写错误的 disclosure 会被视为受限。 默认拒绝：拼写错误 不会意外公开内容，但可能会意外隐藏内容。请仔细检查拼写。
• <bv-topic visibility> 不会让事实变为公开。 它只是信息标签。已脱敏视图 会读取每项事实自身的 disclosure 属性，而不会读取主题级默认设置。

完整模型、规范示例，以及为任何事实选择公开或受限的指南，请参阅 vocabulary.md。

两种记录形式

• 简单形式（--title --body） 会将正文包装在单个 <bv-fact> 中。仅当主题确实是一条事实时才使用（例如“我们使用 OAuth 2.0 和 PKCE”）。 其他情况下，这种包装结构都不正确。
• 丰富形式（--html） 适用于其他所有情况，例如个人资料转储、 决策 + 原因 + 规则 + 事实、错误 + 修复操作手册、研究笔记。

有关完整的元素注册表、架构级属性以及权威的反模式列表，请阅读 vocabulary.md。有关达到提交质量的记录指南，请阅读 record.md。

何时阅读哪些内容

• 首次进入某个仓库，或项目尚无记忆 → onboarding.md
• 检索前 → query.md
• 保存知识前 → record.md
• 选择合适的 <bv-*> 元素 → vocabulary.md
• 定期清理 / 整合 → dream.md

注意：主题采用 <bv-*> HTML（而非 Markdown）。scripts/*.mjs 由 @byterover/skill-runtime 通过 pnpm build:skill 生成；如果缺少这些文件，请先构建。