mirror of
https://github.com/agentscope-ai/ReMe.git
synced 2026-08-28 05:25:04 +00:00
ab66f2bb56
* docs: update ReMe documentation URL * docs: localize ReMe Studio social image * docs(AGENTS): update agent guidelines and repository documentation structure - Clarify coding agent guidance for keeping changes small and consistent - Revise project principle descriptions for clarity and modern terminology - Expand repository map with detailed component and folder explanations - Add configuration and CLI usage instructions, including syntax and merging rules - Elaborate on component, step registration, and application lifecycle processes - Define jobs, steps, and state handling conventions for stateless design - Specify workspace and file safety policies, including path restrictions and locking - Update validation commands and testing environment recommendations - Clarify coding and test conventions, including style and dependency policies - Distinguish documentation boundaries and update website content contribution notes - Reinforce change guardrails to avoid breaking backward compatibility and data loss - Improve svg diagram formatting and textual details in auto dream and proactive flow image * style(docs): fix font-family syntax in SVG style definitions - Correct quotation marks around font-family names in memory-as-file.svg - Standardize font-family formatting by removing unnecessary quotes in reme-blog-architecture.svg - Ensure consistent CSS style formatting within SVG files for better rendering fidelity * docs: add ReMe blog to news * style(docs): inline svg styles and improve text formatting - Convert multiline SVG style tags into single-line for compactness in multiple figures - Remove redundant line breaks in subtitle text elements for consistency - Shorten descriptive texts in SVG figures for clarity and conciseness - Adjust font sizes and text for better readability in SVG elements - Correct whitespace issues in Chinese markdown document for improved formatting - Remove unused style blocks from framework structure SVG for cleaner code
136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
# Auto Link
|
||
|
||
当前实现中，`auto_link` 不是一个单独注册的 Job，而是 `auto_dream` 的 Integrate 阶段能力：`dream_integrate_step` 在把 memory
|
||
unit 写入 `digest/` 时，同时完成 digest 节点召回、去重判断、来源链接和相关节点 wikilink 织入。
|
||
|
||
完整 dream 流程见 [Auto Dream](./auto_dream.md)。通用 wikilink、frontmatter 和 workspace-relative 路径语义见
|
||
[Memory as File](./memory_as_file.md)。面向问答的检索能力见 [Memory Search](./memory_search.md)。
|
||
|
||
## 所在位置
|
||
|
||
`auto_dream` 的默认流程如下：
|
||
|
||
```yaml
|
||
auto_dream:
|
||
steps:
|
||
- dream_extract_step
|
||
- dream_integrate_step # auto_link 的实际发生位置
|
||
- dream_topics_step
|
||
- dream_finish_step
|
||
```
|
||
|
||
Integrate 阶段对每个 unit 独立运行。一个 unit 只落到一个目标 digest 节点，但这个目标节点可以链接多个来源和多个相关 digest
|
||
节点。
|
||
|
||
## 目标
|
||
|
||
`auto_link` 解决的是写入时的图谱质量问题：
|
||
|
||
| 问题 | 处理方式 |
|
||
|-------------------|------------------------------------------------------|
|
||
| 已有相同记忆 | 召回后更新旧节点，而不是重复创建。 |
|
||
| 新旧材料有关联 | 在正文中写入 workspace-relative wikilink。 |
|
||
| digest 与来源断开 | 在 `## Sources` 章节加入指向 daily/resource 的链接。 |
|
||
| 节点只有孤立正文 | 在 CREATE 和 UPDATE 时都补充相关 digest 节点链接。 |
|
||
|
||
## 工具链
|
||
|
||
`dream_integrate_step` 暴露给 Agent 的工具是：
|
||
|
||
```text
|
||
node_search
|
||
read
|
||
frontmatter_read
|
||
write
|
||
edit
|
||
frontmatter_update
|
||
```
|
||
|
||
其中 `node_search` 是为 dream 集成设计的 digest-only 节点召回。它返回 digest 节点的 `path`、front matter 中的 `name`、
|
||
`description` 等节点级信号，不展开正文，也不做普通 search 的 link expansion。
|
||
|
||
`read` 和 `frontmatter_read` 只用于可能相关的候选节点，避免把召回结果全部展开成大上下文。
|
||
|
||
## 链接流程
|
||
|
||
### 1. 召回候选节点
|
||
|
||
Agent 先用 unit 的触发条件、动词、名词、同义词和可能的 failure modes 调用 `node_search`。默认建议用较宽召回，例如
|
||
`limit=20-30`，因为这一步同时服务去重和链接发现。
|
||
|
||
召回结果会被内部分成三类：
|
||
|
||
| 分类 | 含义 | 后续动作 |
|
||
|--------------------|--------------------------------------------------------|---------------------|
|
||
| `same_abstraction` | 触发条件或抽象本质相同，内容实质重叠。 | 作为 UPDATE 目标。 |
|
||
| `related` | 相邻流程、前置条件、失败模式、概念、偏好或上下游知识。 | 写入正文 wikilink。 |
|
||
| `unrelated` | 只是表面相似或无关。 | 忽略。 |
|
||
|
||
### 2. 选择写入动作
|
||
|
||
每个 unit 必须选择一个动作：
|
||
|
||
| 动作 | 链接含义 |
|
||
|---------------|----------------------------------------------------------------------------|
|
||
| `CREATE` | 写入新的 `digest/<bucket>/<slug>.md`，并在新正文里加入来源和相关节点链接。 |
|
||
| `CORROBORATE` | 同一抽象再次出现，追加来源链接，必要时强化描述。 |
|
||
| `REFINE` | 新材料扩展了旧节点，把补充内容插入合适段落，并保留旧链接。 |
|
||
| `CORRECT` | 新材料修正旧节点，用来源链接标出修正依据。 |
|
||
|
||
UPDATE 必须尽量只增不删：不要删除已有 wikilink 或来源条目。这是为了让后续图谱索引和检索不会丢边。
|
||
|
||
### 3. 写来源边
|
||
|
||
来源边是归档在 Markdown 固定章节下的普通 Wikilink：
|
||
|
||
```markdown
|
||
## Sources
|
||
|
||
该决策记录在 [[daily/2026-06-20/session.md]] 中，支撑它的技术证据来自
|
||
[[resource/2026-06-20/paper.md]]。
|
||
```
|
||
|
||
这些边表示 digest 节点的证据来源。纯文本描述不算来源边，因为只有 wikilink 能被 file graph 稳定解析；外层完整句子还必须说明每个来源支持什么，
|
||
裸 Wikilink 单独成行不是合法的 Integrate 输出。更完整的 wikilink
|
||
解析规则见 [Memory as File](./memory_as_file.md#wikilink)。
|
||
|
||
### 4. 写 digest 关联边
|
||
|
||
digest 之间的关联使用完整 workspace-relative 路径，并自然织入正文：
|
||
|
||
```markdown
|
||
这个设计扩展了 [[digest/wiki/hybrid-search.md]]，并使用
|
||
[[digest/procedure/rebuild-index.md]]。评审时遵循
|
||
[[digest/personal/team-review-preference.md]]。
|
||
```
|
||
|
||
## Bucket 差异
|
||
|
||
`auto_link` 的规则会随 unit bucket 调整写入形态：
|
||
|
||
| Bucket | 写入重点 |
|
||
|-------------|--------------------------------------------------------------------------------|
|
||
| `procedure` | 写成 runbook：触发条件、步骤、输入、失败模式。链接前置流程、子步骤、相关偏好。 |
|
||
| `personal` | 写用户、团队、项目特定事实或偏好。链接相关项目、习惯、决策背景。 |
|
||
| `wiki` | 写通用知识、原则、观察、决策先例。链接概念、方法、相邻知识。 |
|
||
|
||
无论 bucket 是什么，都要保留来源边，并尽量把召回到的相关 digest 节点织入正文。
|
||
|
||
## 与 search 的关系
|
||
|
||
`auto_link` 使用的是 `node_search`，不是面向问答的 `search`。
|
||
|
||
| 能力 | 用途 |
|
||
|---------------|---------------------------------------------------------------------|
|
||
| `search` | 面向外部问答，返回 chunk，并可展开上下游 link context。 |
|
||
| `node_search` | 面向 dream 集成，只召回 digest 节点级摘要，用来判断去重和相关链接。 |
|
||
|
||
这个边界很重要：Integrate 阶段需要的是“是否已有相同抽象，以及应该链接哪些节点”，而不是直接把大量正文片段塞进上下文。
|
||
[Memory Search](./memory_search.md) 负责面向用户问题的 chunk 召回、RRF 融合和链接展开。
|
||
|
||
## 失败和重试
|
||
|
||
如果某个 unit 整合失败，`dream_integrate_step` 会记录 `failed_units` 和 `failed_paths`。`dream_finish_step` 不会
|
||
checkpoint 这些来源路径，因此下一次 `auto_dream` 仍会重新处理它们。
|
||
|
||
这保证了 auto_link 的写入具有可重试性：失败不会把输入标成已完成，也不会静默丢失应该建立的 digest 边。
|