[LLM Wiki理论与实践-10]OpenWiki为Coding Agent提供的6个工具函数

LLM Wiki理论与实践-09：将OpenWiki融入Coding Agent为你省点钱介绍了OpenWiki的Code模式，并通过一个简单的实例演示了如何将它整合进Codex。不论是针对Codex还是Claude Code，OpenWiki都是以MCP服务器的形式注册到Coding Agent上，并且采用基于stdio的跨进程通信。OpenWiki的所有功能都提供相应的工具函数来提供，本篇文章就来单独聊聊这些工具函数。

1. 使用程序探索OpenWiki MCP提供的工具列表

我们可以直接通过一个简单的程序来探索OpenWiki MCP服务器提供的所有工具函数。在已经通过执行openwiki --init命令进行OpenWiki初始化的目录下，我们编写了如下的一段程序。如代码所示，我们创建了一个MultiServerMCPClient对象，并添加了一个针对stdio链接的MCP服务器，后者通过执行openwiki mcp命令启动。我们针对这个连接调用MultiServerMCPClient对象的get_tools方法得到一组工具列表，并将每个工具的名称和参数信息输出出来。

from langchain_mcp_adapters.client import MultiServerMCPClient
from typing import cast
import asyncio

client = MultiServerMCPClient(
    {
        "server": {
            "transport": "stdio",
            "command": "openwiki",
            "args": ["mcp"],
        }
    }
)

async def main():
    tools = await client.get_tools(server_name="server")
    for tool in tools:
        print(f"""\
{tool.name}:
  - description: {tool.description}
  - args: """)

        for (name, arg) in tool.args.items():
            print(f"    - {name}:")
            for (k, v) in cast(dict, arg).items():
                print(f"      - {k}: {v}")
        print()

asyncio.run(main())

输出：

openwiki_begin:
  - description: Start or resume OpenWiki repository generation. Returns status=noop for a clean update, otherwise the durable planning/generation run state. An unrecognized `language` fails the call with invalid_input instead of starting a run.
  - args: 
    - root:
      - type: string
      - minLength: 1
    - mode:
      - type: string
      - enum: ['init', 'update']
    - language:
      - type: string
      - minLength: 1
      - description: BCP-47 code, e.g. "ko" (not "Korean").
    - force:
      - type: boolean

openwiki_submit_plan:
  - description: Submit the final canonical page plan. OpenWiki validates it and durably persists the ordered PageJob queue before accepting it.
  - args: 
    - runId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    - pages:
      - type: array
      - items: {'type': 'object', 'properties': {'path': {'type': 'string', 'minLength': 1}, 'title': {'type': 'string', 'minLength': 1}, 'purpose': {'type': 'string', 'minLength': 1}, 'seedPaths': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}, 'relatedPages': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}, 'instructions': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}}, 'required': ['path', 'title', 'purpose'], 'additionalProperties': False}
    - deletePages:
      - type: array
      - items: {'type': 'string', 'minLength': 1}

openwiki_next_page:
  - description: Return the first pending page job, its Claim count, and only stale or unresolved Claims requiring an explicit decision; current issue-free Claims remain compact unless inspected on demand.
  - args: 
    - runId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

openwiki_inspect_page_claims:
  - description: Return the current pending page's complete Claim set without opaque evidence versions. Use only before intentionally revising or removing otherwise-current content; focused updates normally needonly the issue Claims returned by openwiki_next_page.
  - args: 
    - runId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    - jobId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

openwiki_submit_page:
  - description: Complete the current page job after its Markdown is written. Submit only sparse decisions: confirmedClaimIds for rechecked issue Claims retained unchanged, claims for revisions or additions, andretractedClaimIds for removals. Other current Claims are retained automatically. The final page and reconciled Claim set must agree.
  - args: 
    - runId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    - jobId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    - confirmedClaimIds:
      - type: array
      - items: {'type': 'string', 'minLength': 1}
    - claims:
      - type: array
      - items: {'type': 'object', 'properties': {'id': {'type': 'string', 'minLength': 1}, 'statement': {'type': 'string', 'minLength': 1}, 'evidence': {'minItems': 1, 'type': 'array', 'items': {'type': 'object', 'properties': {'resource': {'type': 'string', 'minLength': 1}}, 'required': ['resource'], 'additionalProperties': False}}}, 'required': ['statement', 'evidence'], 'additionalProperties': False}
    - retractedClaimIds:
      - type: array
      - items: {'type': 'string', 'minLength': 1}

openwiki_finish:
  - description: Finish only after every PageJob is complete. Runs deterministic deletion, validation, indexing, provenance, Claims finalization, and run metadata persistence.
  - args: 
    - runId:
      - type: string
      - format: uuid
      - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

输出结果呈现了如下六个工具函数：

• openwiki_begin: 启动或恢复一个Wiki生成任务。传入init/update和语言，返回一个持久化的runId用于追踪整个生命周期（如果代码无更新则返回 noop）。
• openwiki_submit_plan: 向OpenWiki提交全局的页面规划蓝图。模型在这里定义要生成哪些页面、页面标题、目的以及相关的关联文件，校验通过后会在后台生成一个有序的页面任务队列（PageJob queue）。
• openwiki_next_page: 从任务队列中获取下一个待处理的页面任务。它会返回该页面的ID，并聪明地只返回那些过期或未解决的Claims（声明），从而极大节省模型的上下文Token。
• openwiki_inspect_page_claims: 深度检查当前页面的完整Claim集合。通常不需要用，只有在模型需要主动修改或删除原本正常的既有内容时，才用它来获取全量上下文。
• openwiki_submit_page: 提交当前页面生成的Markdown内容及对应的Claim 变更决策。模型只需提交新增、修改或撤回的稀疏数据（Sparse decisions），系统会自动保留未变动的旧Claim，并校验页面与证据是否一致。
• openwiki_finish: 在队列中所有页面任务完成后进行收尾。触发确定性的清理、最终校验、建立索引、固化出处（Provenance）以及持久化运行元数据，确保最终产出是一个“零幻觉”的干净Wiki。

2. 针对工具函数的调用流程

在LLM Wiki理论与实践-09：将OpenWiki融入Coding Agent为你省点钱介绍了openwiki integrations install命令内部执行的三个操作，其中一个就是在%userprofile%.agents\skills或者~/agents/skills目录下添加OpenWiki对应的Skill。这个Skill提供的处理流程就包含针对上述六个工具函数的调用。

---
name: openwiki
description: Initialize or update an OpenWiki repository wiki using the OpenWiki resumable page-job lifecycle. Use when asked to document a repository, initialize OpenWiki, update OpenWiki after source changes, resume an interrupted OpenWiki run, or repair stale generated documentation.
---

# OpenWiki

OpenWiki owns run state, the page queue, Claims validation/persistence, indexes,
provenance, and finalization. You own semantic repository research and the prose
for the single page OpenWiki assigns you.

## Required sequence

1. Resolve the exact Git top-level with `git rev-parse --show-toplevel` (or
   `git -C <path> rev-parse --show-toplevel` for an explicit target).
2. Call `openwiki_begin` with that absolute root and mode `init` or `update`.
   An active run may have been started by native OpenWiki or another supported
   host; always continue the durable run and queue returned by `openwiki_begin`.
3. If `openwiki_begin` returns `status: "noop"`, report that no update is needed
   and stop.
4. If it returns `phase: "planning"`:
   - first map repository manifests, major directories, entrypoints, and public
     surfaces; then trace representative end-to-end flows through callers,
     state/persistence, failure handling, configuration, operations, and
     integrations; finally inspect focused tests and neighboring implementations
     to verify boundaries, invariants, and non-obvious connections;
   - stop once the major systems, behaviors, and relationships are grounded;
     avoid exhaustive file-by-file inventory;
   - design a repository-specific documentation taxonomy around meaningful
     systems and workflows rather than mirroring source directories;
   - use hierarchical paths for meaningful architecture, concept, workflow,
     operations, integration, and testing groups instead of a flat dump of
     unrelated top-level pages; do not plan generated `index.md` pages;
   - populate `relatedPages` with useful conceptual and workflow neighbors so
     readers can navigate across system boundaries;
   - for init, include `/openwiki/quickstart.md`;
   - for update, never delete `/openwiki/quickstart.md`; if the update adds,
     deletes, moves, or materially regroups wiki pages, include quickstart so its
     task-routing map is refreshed;
   - an update with no required page edits or deletions may submit `pages: []`;
   - call `openwiki_submit_plan` with final canonical page paths, concise page
     purposes, useful seed source paths, meaningful `relatedPages`, page-relevant
     global `instructions`, and any page deletions required by an update.
5. Repeatedly call `openwiki_next_page`.
6. For each pending page job:
   - use the `language` returned by `openwiki_begin` as the output language;
   - read the current page first when it exists;
   - research that page's topic using native repository tools, starting from its
     seed paths but following callers, callees, dependencies, schemas, state
     owners, integration boundaries, tests, and operational contracts when
     needed;
   - preserve accurate unaffected content on update;
   - write exactly the assigned Markdown page;
   - current issue-free Claims are retained automatically; do not resubmit them;
   - call `openwiki_inspect_page_claims` only before intentionally revising or
     removing otherwise-current content whose Claim ids are not included in the
     pending job;
   - call `openwiki_submit_page` with only sparse decisions: put rechecked issue
     Claims retained unchanged in `confirmedClaimIds`, put revised existing and
     genuinely new Claims in `claims`, and put removed Claims in
     `retractedClaimIds`. If validation rejects the page or payload, correct it
     and retry; completion requires one successful submission.
7. When `openwiki_next_page` returns `status: "complete"`, call
   `openwiki_finish`.
8. Report success only after `openwiki_finish` returns `complete`.
...

整个流程是一个闭环的Begin -> Plan -> (Next -> Submit)* -> Finish循环。OpenWiki掌控着生命周期、队列和Claim的验证与持久化，而模型只负责单个页面的语义研究与内容撰写，实现了工程控制与AI生成能力的完美解耦。整个执行流程是一个严格由工具函数驱动的闭环状态机，强调按序调用、不可跳步。具体流程如下：

• 启动与规划：首先调用openwiki_begin启动任务。若返回noop则直接终止；若进入 planning阶段，模型需阅读代码设计页面蓝图，随后调用 openwiki_submit_plan提交计划，系统将其固化为有序的任务队列。
• 循环领取任务：进入页面生成循环，反复调用openwiki_next_page领取具体的页面任务（此时系统会精简过期的 Claims以节省Token）。
• 按需检查：若模型需要修改未报错的正常内容，必须调用openwiki_inspect_page_claims获取完整的claim_id集合。
• 内容提交与校验：完成页面撰写后，调用 openwiki_submit_page 提交内容与“稀疏”的 Claim 决策（确认、修改或撤回）。若校验失败，模型必须修正并重复调用该函数，直到成功。
• 队列终结：当openwiki_next_page返回 complete时，退出循环，调用openwiki_finish触发最终校验与索引固化。只有该函数返回成功后，流程才算真正结束。

3. openwiki_begin

openwiki_begin是OpenWiki的启动与状态机入口。它的核心功能是：校验目标Git仓库根目录，并根据init或update模式启动或恢复任务。通过返回持久化的runId，它确保了长周期任务的可中断与恢复；若探测到代码无变更，则直接返回noop短路流程。此外，它还负责接收目标语言，并输出当前阶段（如planning）及变更统计，为后续的页面规划与生成奠定状态基础。OpenWiki使用如下这个begin函数来处理调用请求。

async begin(input: BeginRequest): Promise<unknown>

export interface BeginRequest {
  mode: HostRunMode;
  language?: string;
  force?: boolean;
}
export type HostRunMode = "init" | "update";

4. openwiki_submit_plan

openwiki_submit_plan是OpenWiki 的全局规划提交入口。它的核心功能是接收大模型对仓库代码的全局分析结果，定义需要生成的Wiki 页面层级、目标路径、用途以及关联的代码种子文件。提交后，OpenWiki 会严格校验该规划的合法性，并将其持久化为一个有序的页面任务队列（PageJob queue）。它还负责处理更新模式下的页面删除请求，从而将无序的文档构想转化为可控的串行生成任务流。OpenWiki使用如下这个submitPlan函数来处理调用请求。

async submitPlan(input: SubmitPlanRequest): Promise<unknown>

export type SubmitPlanRequest = z.infer<typeof SubmitPlanInput>;
export const SubmitPlanInput = z
  .object({
    runId: z.string().uuid(),
    pages: z.array(PlanPageInput),
    deletePages: z.array(CanonicalString).optional(),
    deferUnplannedClaimIssues: z.boolean().optional(),
  })
  .strict();
export const PlanPageInput = z
  .object({
    path: CanonicalString,
    title: CanonicalString,
    purpose: CanonicalString,
    seedPaths: z.array(CanonicalString).optional(),
    relatedPages: z.array(CanonicalString).optional(),
    instructions: z.array(CanonicalString).optional(),
  })
  .strict();
const CanonicalString = z.string().trim().min(1);

5. openwiki_next_page

openwiki_next_page是 OpenWiki的任务队列调度器。它的核心功能是从持久化的PageJob队列中按顺序提取下一个待处理的页面任务，并返回其唯一run_id。为了极致节省大模型上下文，它仅返回该页面中**过期（stale）或未解决（unresolved）**的Claim供模型重新检查。当所有任务处理完毕时，它会返回complete状态，引导流程进入收尾阶段。OpenWiki使用如下这个nextPage函数来处理调用请求。

async nextPage(input: NextPageRequest): Promise<unknown>

export type NextPageRequest = z.infer<typeof NextPageInput>;
export const NextPageInput = RunInput;
export const RunInput: z.ZodType<RunRequest> = z
  .object({
    runId: z.string().uuid(),
  })
  .strict();
export interface RunRequest {
  runId: string;
}

6. openwiki_inspect_page_claims

openwiki_inspect_page_claims是OpenWiki的全量声明检查器。它的核心功能是返回当前待处理页面中完整且详尽的Claim集合（包含所有未过期的正常声明）。它专用于一种场景：当模型在更新页面时，意图主动修改或删除原本无报错的既有内容，必须调用此工具获取精确的Claim ID，以确保后续通过openwiki_submit_page提交的稀疏变更能被正确关联和校验。OpenWiki使用如下这个inspectPageClaims函数来处理调用请求。

async inspectPageClaims(input: InspectPageClaimsRequest): Promise<unknown>

export type InspectPageClaimsRequest = z.infer<typeof InspectPageClaimsInput>;
export const InspectPageClaimsInput = z
  .object({
    runId: z.string().uuid(),
    jobId: z.string().uuid(),
  })
  .strict();

7. openwiki_submit_page

openwiki_submit_page是 OpenWiki的单页内容与声明提交入口。它的核心功能是接收模型撰写完毕的当前页面Markdown 内容，以及一份稀疏的声明决策（包含重新确认、修改新增或撤回的 Claim）。它负责校验最终页面文本与底层证据声明是否一致，并自动保留未变动的旧Claim。如果校验失败，它会拒绝接收并报错，要求模型修正后重试，从而确保每一页的生成质量与代码事实严格对齐。OpenWiki使用如下这个submitPage函数来处理调用请求。

async submitPage(input: SubmitPageRequest): Promise<unknown>

export type SubmitPageRequest = z.infer<typeof SubmitPageInput>;
export const SubmitPageInput = z
  .object({
    runId: z.string().uuid(),
    jobId: z.string().uuid(),
    confirmedClaimIds: z.array(CanonicalString).optional(),
    claims: z.array(ProposedPageClaimInput).optional(),
    retractedClaimIds: z.array(CanonicalString).optional(),
  })
  .strict();

8. openwiki_finish

openwiki_finish是 OpenWiki的全局收尾与固化执行器。它的核心功能是在确认所有页面任务（PageJob）均已完成后，触发一系列确定性的收尾工作：包括清理过期文件、执行最终全局校验、建立文档索引、固化出处（Provenance）以及持久化运行元数据。只有当该工具成功返回，标志着整个OpenWiki的生成或更新流程彻底结束，确保最终产出一个结构完整且零幻觉的干净Wiki仓库。OpenWiki使用如下这个finish函数来处理调用请求。

async finish(input: RunRequest): Promise<unknown> 

export interface RunRequest {
  runId: string;
}