Lawang Onboard

Lawang Onboard

权限感知型 AI 入职辅导。 集成在 IBM Bob 中的入职助手，帮助新工程师了解代码库，并且只展示他们有权查看的内容。

由 Lawang Onboard 团队为 IBM Bob 2.0 Hackathon（lablab.ai，2026 年 9 月 25 日至 27 日）打造。

问题

新工程师，或受聘负责某个模块的承包商，需要花上数周时间才能了解代码库为何如此设计。答案散落在提交信息、架构决策记录和拉取请求评审中，但没人会在入职第一天阅读这些内容。访问权限也非全有即全无：要么新人能看到一切，包括 AI 助手读入上下文的所有内容；要么就只能等别人来解释。

功能

在 IBM Bob 中打开代码库，切换到 Onboard 模式，然后提问：

• /tour：逐个模块展示你能看到的内容。
• /trace webhook：逐步说明 webhook 如何变成一条记录。
• /why internal/ingress：某个路径背后的决策和评审。
• “我可以先接手什么？”

Bob 根据代码及其历史作答，并引用用到的每一项内容。每条上下文都带有一个 范围；工程师的角色映射到一组范围；角色由连接所用的令牌决定；Lawang Onboard MCP 服务会在模型看到任何内容之前进行过滤。承包商的会话无法泄露从未提供给它的内容，而且每个回答都会以被屏蔽的内容收尾：

Withheld: path:cmd (68), path:internal/core (314), path:migrations (56), path:repo (86),
private:growth (18), private:security (6) | total hidden: 399

承包商	维护者

结果

数据于 9 月 26 日使用承包商角色测得；每个问题都在一个全新的 Bob 任务中提出，测试者是未参与服务开发的团队成员。完整报告：docs/benchmark.md。

	结果
十个入职问题	10 个中答对 10 个；平均每个回答耗时 36 s，花费 0.16 Bobcoins
与手动回答相比	三个问题分别用时 46 s 对比 210 s，其中一个问题无法通过手动回答
泄露探测（提示注入、直接调用 get、冒充其他角色、搜索、“猜测”）	5 次中全部 5 次成功拦截；角色范围之外的内容均未进入模型
Bob 代码评审	发现 2 个实际问题（未认证的演示 API、get 中的存在性预言机），两者均已修复并重新检查
屏蔽数量	每次运行都与根据 roles.yaml 和语料库独立重新统计的结果一致
泄露测试	11 个测试函数，每个都覆盖全部三种角色，并包含植入的注入内容；CI 中运行 go test -race ./...

工作原理

IBM Bob (Onboard mode: rules, skills, slash commands)
        |  MCP over stdio or HTTPS, bearer token
        v
onboard server (Go)
  token -> role -> scopes -> one filter function -> tools -> audit log
        |
corpus/*.jsonl  (610 items: files, docs, ADRs, commits, PRs, reviews, issues, each with scopes)

• 范围来自 roles.yaml：路径 glob（首次匹配优先）、标签（growth 标签会将问题设为私密）和类型。每项内容都必须满足其所有范围要求；没有范围的内容对所有人都不可见。
• 工具：whoami、map_system、search、get、trace_feature、why、setup_guide、starter_tasks、withheld。每个工具都会先进行过滤，并且只根据可见内容生成回答。隐藏 ID 和不存在的 ID 会得到相同回答。
• Onboard 模式只能使用 MCP 工具和技能，不能访问文件系统，因此 Bob 唯一能看到的代码视图就是经过过滤的视图。其规则要求先调用 whoami、引用项目 ID、将语料库文本视为数据、把提案标记为提案，并以 Withheld 行收尾。
• 令牌采用恒定时间比较；未知、为空或存在歧义的令牌都会被拒绝。演示页面的 API 使用相同的令牌。

设计说明：docs/design.md。

试用

• 在线演示： https://lawang-onboard.samsulhadi.com（粘贴角色令牌即可查看该角色的视图）。
• 连接客户端： IBM Bob、Claude Code、Cursor 和 VS Code 的配置如下，可通过已发布的镜像使用 stdio 连接，也可通过托管服务使用 HTTPS 连接。

连接 MCP 客户端

server.json 声明了两种接入方式，通过这两种方式提供的九个工具完全相同：

传输方式	地址	所需条件
stdio	镜像 ghcr.io/gablooge/lawang-onboard:0.1.1，使用 -stdio 运行	Docker，以及由你选择的密钥
streamable-http	https://lawang-onboard.samsulhadi.com/mcp	服务运营者提供的角色令牌

0.1.1 是要拉取的标签；其中的二进制文件仍会将 0.1.0 报告为 serverInfo.version，因此你的客户端可能会显示该版本。使用 stdio 时，你是运营者：任选一个密钥，将其分配给某个角色，并将 ONBOARD_TOKEN 设置为相同的值。该角色决定你能看到什么；镜像中包含 Lawang 演示语料库，因此无需进行其他设置。使用 HTTPS 时，令牌由我们提供，请向我们索取。

不要将密钥放进任何要提交的文件中。下面的 Bob、Claude Code 和 Cursor 配置片段会从环境变量中读取密钥，因此请在启动客户端前导出该变量；下面的 VS Code 配置片段不会读取环境变量，VS Code 会改为提示你输入一次。这两个值有意设置为相同：一个用于命名角色，另一个用于声明此客户端所代表的角色。

read -rs ONBOARD_TOKEN && export ONBOARD_TOKEN   # typed, so it stays out of your shell history
export ONBOARD_TOKEN_CONTRACTOR="$ONBOARD_TOKEN"

然后选择你的客户端。每个配置片段都标明了其对应的文档及查阅日期；这些客户端会更改配置格式，如果配置片段无法使用，请查看对应文档。

IBM Bob

对于通过 stdio 连接的本地服务，将 .bob/mcp.example.json 复制到 .bob/mcp.json；对于托管服务，则复制 .bob/mcp.remote.example.json，然后填入令牌、重新加载 MCP 服务、切换到 Onboard 模式并输入 /tour。这两个文件都会将令牌以明文形式保存，而 .gitignore 会将文件排除在 git 之外。对于本地服务，这正是“在本地运行”下的工作流所需要的：scripts/use-role.py 会替你将令牌写入该文件的 env 对象。远程服务的令牌需要由你自行粘贴到 headers 中，因为它没有 env 对象，而且该脚本不会修改它。下面的配置片段会改为将令牌保存在环境变量中。

使用已发布的镜像通过 stdio 运行，无需 Go 工具链：

{
  "mcpServers": {
    "lawang-onboard": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ONBOARD_TOKEN", "-e", "ONBOARD_TOKEN_CONTRACTOR",
               "ghcr.io/gablooge/lawang-onboard:0.1.1", "-stdio"],
      "env": {
        "ONBOARD_TOKEN": "${env:ONBOARD_TOKEN}",
        "ONBOARD_TOKEN_CONTRACTOR": "${env:ONBOARD_TOKEN_CONTRACTOR}"
      }
    }
  }
}

这样，文件中保存的只是变量名，而不是你的密钥。以下是 Bob 的三个相关细节，根据 2026 年 10 月 12 日的测试结果整理（Bob IDE 2.2.1 和 Bob Shell 2.0.5 使用相同的 MCP 客户端）：

• Bob 会从自身环境中展开 ${env:NAME}。已测试 env 和 headers；args 也会对整个条目进行同样的遍历。单独的 ${NAME} 不会展开，并会以原样文本传递；在从旧笔记中复制 ${VAR} 前，值得留意这一点。
• env 对象确实发挥着作用：Bob 会为 stdio 服务提供固定的允许列表（HOME、LOGNAME、PATH、SHELL、TERM、USER），再加上条目自身的 env，不会提供其他变量。因此，单独使用 -e ONBOARD_TOKEN 不会传递任何值，镜像会以错误 onboard: ONBOARD_TOKEN is not set 退出。请保留这两部分设置。
• 请在启动 Bob 前导出这些变量。之后在另一个终端中设置变量，不会传递给已在运行的 Bob。

Claude Code

以下两个命令来自claude mcp add参考文档（2026 年 10 月 12 日查阅）。服务器启动时，--env 的值和标头值会从环境变量中展开，因此写入配置的是 ${...} 文本，而不是你的密钥。-- 之后的所有内容都会原样传递给服务器，这样 docker run 才能保留自己的标志。

通过映像使用 stdio：

claude mcp add --env 'ONBOARD_TOKEN=${ONBOARD_TOKEN}' \
  --env 'ONBOARD_TOKEN_CONTRACTOR=${ONBOARD_TOKEN_CONTRACTOR}' --transport stdio lawang-onboard \
  -- docker run -i --rm -e ONBOARD_TOKEN -e ONBOARD_TOKEN_CONTRACTOR \
     ghcr.io/gablooge/lawang-onboard:0.1.1 -stdio

通过托管服务器使用 HTTPS：

claude mcp add --transport http lawang-onboard https://lawang-onboard.samsulhadi.com/mcp \
  --header 'Authorization: Bearer ${ONBOARD_TOKEN}'

这两条命令都会写入本地作用域，也就是仅对当前项目生效；若要对所有项目生效，请添加 --scope user。单引号很重要：它们可以阻止 shell 将令牌展开后存入命令。在 CLI 2.1.293 中以默认作用域进行了检查：条目会写入 ~/.claude.json 中当前项目的路径下，存储的是 ${...} 文本；导出变量时，claude mcp list 会报告 Connected，未导出时则会报告 Failed to connect，并指出缺少哪些变量。

关于 HTTPS 条目，有一个需要了解的隐性失败情况。在“读取为空的凭据变量”一节中，该页面称，某些类似凭据的名称在远程服务的 url 和 headers 中读取为空，而不是展开为变量值。页面给出了三个类别及示例，没有列出具体名称，并说明这些类别之外的名称会按原样展开。ONBOARD_TOKEN 不属于这些类别，而且在 CLI 2.1.293 中确实展开了；验证时使用了一个会记录收到的标头的本地端点。如果你的变量读取为空，发出的标头就会变成一个不带令牌的 Bearer ，此服务器会返回 401。快速检查方法是运行 claude mcp list；要查看具体变量名，可运行 claude --debug-file /tmp/claude-debug.log 并搜索 "never expanded toward a remote server"。

Cursor

在项目中的 .cursor/mcp.json，或适用于所有项目的 ~/.cursor/mcp.json 中，使用 mcpServers 配置。Cursor 会解析 command、args、env、url 和 headers 中的 ${env:NAME}。内容来自Cursor 的 MCP 文档（2026 年 10 月 12 日查阅）。

通过映像使用 stdio。该页面的 stdio 字段表将 type 标为必填项，值为 "stdio"，但所有 stdio 示例都没有这一字段，因此此代码片段遵循字段表：

{
  "mcpServers": {
    "lawang-onboard": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ONBOARD_TOKEN", "-e", "ONBOARD_TOKEN_CONTRACTOR",
               "ghcr.io/gablooge/lawang-onboard:0.1.1", "-stdio"],
      "env": {
        "ONBOARD_TOKEN": "${env:ONBOARD_TOKEN}",
        "ONBOARD_TOKEN_CONTRACTOR": "${env:ONBOARD_TOKEN_CONTRACTOR}"
      }
    }
  }
}

通过托管服务器使用 HTTPS：

{
  "mcpServers": {
    "lawang-onboard": {
      "url": "https://lawang-onboard.samsulhadi.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ONBOARD_TOKEN}" }
    }
  }
}

远程条目由 url 和可选的 headers 组成；文档没有指定传输字段，Cursor 会自行确定使用可流式 HTTP。

VS Code

在工作区的 .vscode/mcp.json 中，或在用户配置文件中的同名文件里，使用 servers 配置。字段和变量来自 MCP 配置参考（2026 年 10 月 12 日查阅）：stdio 使用 type、command、args、env 和 envFile；远程服务使用 type、url 和 headers。该页面介绍了 ${input:id} 和 ${workspaceFolder}，但没有介绍 ${env:NAME}，因此令牌需通过 inputs 条目提供：VS Code 会在首次使用时询问一次，并保存以供后续使用。这里的任何配置都不会读取你导出的环境变量。

通过映像使用 stdio：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "onboard-token",
      "description": "Lawang Onboard role token",
      "password": true
    }
  ],
  "servers": {
    "lawang-onboard": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ONBOARD_TOKEN", "-e", "ONBOARD_TOKEN_CONTRACTOR",
               "ghcr.io/gablooge/lawang-onboard:0.1.1", "-stdio"],
      "env": {
        "ONBOARD_TOKEN": "${input:onboard-token}",
        "ONBOARD_TOKEN_CONTRACTOR": "${input:onboard-token}"
      }
    }
  }
}

通过托管服务器使用 HTTPS。请将上方代码块中的 inputs 数组保留在文件中：如果只保留此条目，${input:onboard-token} 将无法解析，VS Code 会拒绝该配置。

{
  "servers": {
    "lawang-onboard": {
      "type": "http",
      "url": "https://lawang-onboard.samsulhadi.com/mcp",
      "headers": { "Authorization": "Bearer ${input:onboard-token}" }
    }
  }
}

同一页面还介绍了位于工作区根目录、可移植的 .mcp.json，其中使用 mcpServers 而非 servers，这与上方 Bob 和 Cursor 代码块的格式一致。code --add-mcp 命令见另一页面VS Code 中的 MCP 服务（2026 年 10 月 12 日查阅）；其示例使用一个带转义双引号的 JSON 参数，只涵盖 name、command 和 args，因此若条目包含 env 或 headers，请使用文件进行配置。

此服务器也已列入 MCP Registry，名称为 io.github.gablooge/lawang-onboard。

Bob 中有而其他地方没有的内容

九个工具在每个客户端中都相同，但围绕这些工具的指导并不相同。Onboard 模式的规则、四项技能（tour、trace、why、first-week）和三个斜杠命令都位于 .bob/ 中，采用 Bob 自己的格式；目前此服务尚未通过 MCP 提供它们。因此，连接此服务的 Claude Code、Cursor 或 VS Code 用户会获得九个工具，但其他指导需要自行补充：首次调用应为 whoami；导览会并行查询此角色可见的各个模块，再合并结果；每项陈述都要引用条目 ID；答案最后要附上 Withheld 行。这些客户端确实会根据筛选后的语料库回答入门问题，而且服务对它们的工具调用所做的筛选与对 Bob 的筛选完全相同（见下方的限制）。只是它们不会以导览的形式运行导览。协议为这类指导提供了位置，但这里为空：对已发布的映像调用 prompts/list 会返回空列表。仍未完成的唯一一项 P2 计划，是将这四项技能作为 MCP 提示词提供，让任何客户端都能调用；详见 PLAN.md。

有一项限制值得明确说明，因为我们无法通过设置来解决。只有当此服务是模型查看代码的唯一途径时，筛选才有效。 Bob 的 Onboard 模式配置为不允许访问文件系统，因此筛选后的语料库就是模型能获取的全部内容。Claude Code、Cursor 和 VS Code 默认会读取你的工作树；模型只要能打开文件，就不必向我们索取：它能看到已检出的所有内容，无论 roles.yaml 如何设置。我们发布的任何内容都不会改变这一点，我们这边也没有任何选项可以做到这一点。如果你想了解某个角色能看到什么，请使用无法访问文件的客户端或模式，或者使用没有代码仓库克隆副本的机器进行连接。否则，未提供内容的计数描述的是语料库（这一点依然属实），而不是你的磁盘。

在本地运行

需要 Go 1.25。

cp .env.example .env                 # set the three role tokens
cp .bob/mcp.example.json .bob/mcp.json
scripts/use-role.py contractor       # writes that role's token into .bob/mcp.json

在 IBM Bob 中打开文件夹，重新加载 MCP 服务，选择 Onboard 模式，然后开始提问。Bob 会通过标准输入输出流启动服务。

要使用网页和 HTTP 端点：

set -a; . ./.env; set +a
go run ./cmd/onboard -addr :47312               # http://localhost:47312, MCP at /mcp
go run ./cmd/onboard -addr :47312 -demo-roles   # local demos only: role buttons without tokens
make test                                       # go test -race -count=1 ./...

托管方式（Docker 和 Cloudflare Tunnel，make up）：docs/deploy.md。

如果想完全跳过 Go 工具链，请改用已发布的映像：每种客户端的操作片段都位于连接 MCP 客户端中。

在自己的代码仓库中使用

这个演示会回答关于 Lawang 的问题，但服务本身并非专门针对它构建。它只读取语料库和角色文件。导出需要 Python 3 和 git，服务需要 Go 1.25 或 Docker。 以下所有命令都在此代码仓库的克隆目录中运行，所有生成内容都放在 git 会忽略的 local/ 下。

1. 导出。 将其指向你代码仓库的本地克隆：

   make corpus REPO=../myrepo GITHUB=me/myrepo OUT=local/corpus
   

   这会从克隆目录中写入文件、文档和提交，并从 GitHub 获取拉取请求、审查和议题（公开代码仓库无需令牌；对于私有代码仓库或大型代码仓库，请设置 GITHUB_TOKEN）。GITHUB= 后面留空会跳过 GitHub，且不会发起网络请求。对于由组织拥有的代码仓库，直接运行脚本并添加 --owner <your login>。

   导出会移除和不会移除的内容。 它会替换固定列表中的令牌格式（GitHub、Slack、AWS 密钥 ID、Stripe、Google、GitLab、npm、JWT、bearer 值、PEM 私钥）、URL 中的密码，以及配置文件中与键名同一行的字面值（键名以 password、secret、token 或 api_key 结尾）；但如果值看起来像变量名（DB_PASSWORD_VAR）或引用（var.db_password），则不会替换。在提交消息和 GitHub 文本中，它还会替换电子邮件地址和 IP 地址，并将所有非所有者和非机器人作者写为 <user>。它会排除符号链接、锁定文件、压缩文件、node_modules、vendor、third_party，以及名称中包含 secret、credential 或 passw 的配置文件。 它不会移除：提交或拉取请求文本中的 @mentions 和姓名、包含登录名的 GitHub noreply 地址、它不认识格式的密钥、存储在中性键名下的密钥，或源代码中赋值的密钥（.py 文件中的 PASSWORD = "..."）。因此，这只是道防线，并非保证。计数会打印出来并保存在 local/corpus/manifest.json 中；分享语料库前请先检查。未经任何清理的原始 GitHub 响应会缓存在语料库旁边的 local/.corpus-raw/ 中；该目录会在 git 中忽略自身，且永远不会被挂载或提供服务。

2. 说明谁能看到什么。

   cp roles.example.yaml local/roles.yaml
   

   修改 glob 模式以匹配你的目录树。每一行都有注释。按模板当前的写法，忘记列出的目录只会显示给维护者角色。只要你不将最后一条规则的作用范围（unlisted:repo）设为其他角色可用，这一点就一直成立；文件头部说明了如果不这样做会有哪些变化。

3. 运行。 每个角色都需要一个令牌，放在其 token_env 指定的变量中。没有令牌时，页面可以加载，但每次调用都会返回 401：

   cp .env.example .env    # then set ONBOARD_TOKEN_MAINTAINER, _EMPLOYEE and _CONTRACTOR
   

   使用 Go：

   set -a; . ./.env; set +a
   go run ./cmd/onboard -addr :47312 -corpus local/corpus -roles local/roles.yaml
   

   或使用已发布的镜像，将两个目录挂载到演示配置对应的目录上：

   docker run --rm -p 47312:47312 --env-file .env \
     -v "$PWD/local/corpus:/app/corpus:ro" -v "$PWD/local/roles.yaml:/app/roles.yaml:ro" \
     ghcr.io/gablooge/lawang-onboard:0.1.1
   

   MCP 端点为 http://localhost:47312/mcp，页面位于 /。使用 stdio 时，从连接 MCP 客户端中复制客户端的 docker run 配置，并在其参数中添加两个 -v 挂载，使用绝对路径（那里没有 shell 可展开 $PWD）；该配置不使用 -p。

你能获得什么取决于代码仓库的内容。导览、搜索、get、trace_feature 和 why 适用于任何导出内容。setup_guide 会读取 README、Makefile 和 .github/workflows/。starter_tasks 需要 GitHub 议题和 label_areas 条目。

IBM Bob 的使用方式

IBM Bob 既是该产品的运行环境，也是构建该产品的工具。Onboard 模式、其规则、四项技能（tour、trace、first-week、why）和三个斜杠命令构成了用户界面。Plan 模式设计了服务，Agent 模式编写了全部代码和测试，Ask 模式检查了是否存在泄露，Onboard 模式运行了基准测试。共执行 36 项 Bob 任务，使用了团队 80 个 Bobcoins 中的 46.6 个；每项任务都有截图，存放在 bob_sessions/ 中，并在台账中都有一条记录（Samsul、Ryan）。详情以及在 Bob 之外完成的工作：docs/submission/bob-usage.md。

数据与隐私

请参阅 DATA_SOURCES.md 和 PRIVACY.md。演示语料库是团队自己的开源代码库 gablooge/lawang；未使用任何客户端、机密、个人或社交媒体数据。角色均为合成角色。

团队

• Samsul Hadi（负责人）
• Ryan Rizki

许可证

MIT