Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AI_ENTRYPOINT.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,16 @@ Do not create task branches for ordinary deposits.

Use branch + PR for procedure, policy, code, structure, cleanup, risky/bulky imports, many existing-file edits, or explicit review.

## One Active Deposit Per Workspace

LabNote supports one active writer at a time per live workspace. People and agents may read and prepare material in parallel; simultaneous deposits, including agent swarms, are unsupported. Human operators sharing a workspace must coordinate turns across all sessions, tools and copies publishing to it. This is an operating rule, not an enforced lock or automatic queue.

A human-assigned current-run visitor handle identifies a session; it neither authorizes a deposit nor reserves a writing turn. Before any write, including visitor registration, confirm with the human that this specific deposit is authorized and no other writer is active in the same workspace. If another writer is active or the turn is unclear, stop before writing and ask the human. Do not infer a free turn from a unique handle or an apparently idle repository.

The turn covers the complete authorized deposit: its artifacts, required JSON records and any required regenerated views. Verify the complete deposit at the agreed destination—local, GitHub or both—before reporting completion. A draft or local commit is not proof of publication to GitHub.

If a write fails or its outcome is uncertain, preserve prepared work, report the failed, partial or unverified outcome and stop for human direction. Check what actually landed before any authorized retry; do not blindly replay, overwrite conflicting work or force-push as recovery. The human must resolve the outstanding turn before another writer starts. Follow the completion and recovery steps in `lobby/ROUTINE_DEPOSIT_QUICKSTART.md`.

## Direct-deposit boundary

Direct routine deposits are content-plane work only: their artifacts and canonical records may be written under `datadrops/`, `responses/`, `messages/`, `notifications/`, `registry/packets/`, `registry/responses/`, `registry/messages/`, `registry/notifications/`, `registry/visits/`, `registry/visitors/`, and `registry/tags/proposed/`, together with the generated views `registry/INDEX.md` and `registry/*_registry.csv` when `scripts/generate_registry_views.py` regenerates them from canonical records created or changed in the same deposit.
Expand Down
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

CapstanAI LabNote is a lightweight, file-based project ledger for people working across AI assistants, coding agents and separate chats. It keeps selected sources, handoffs, reviews, decisions and next actions in ordinary Markdown files and structured JSON records—so the next session can pick up the project thread.

You decide what belongs in the record and what requires review. A shared entry route gives each AI a clear reading path, defined places to leave work and stopping points for human decisions. Basic ledger use needs no LabNote background service, database or model API key.
You decide what belongs in the record and what requires review. A shared entry route gives each AI a clear reading path, defined places to leave work and stopping points for human decisions. Basic ledger use needs no LabNote background service, MCP server, database or model API key.

CapstanAI LabNote is the name of this standalone ledger. It works without a separate CapstanAI service or engine.

Expand Down Expand Up @@ -103,6 +103,10 @@ registry/ ← what happened, when and by whom

A session enters, reads the relevant route, contributes what it needs to contribute, leaves a traceable record and stops. The human remains in charge. An AI may suggest a record worth making, but it waits for the human to start or approve that step.

**One deposit at a time, per workspace.** People and AI agents may read, research and prepare material in parallel, but simultaneous deposits—including agent swarms—are unsupported. The human authorises one contributor's deposit, waits for the whole deposit to be verified in the intended local workspace, GitHub repository or both, and receives the completion report before authorising the next. People sharing a workspace must coordinate those turns across all sessions and tools.

A human-assigned contributor handle identifies a session; it does not grant write permission or reserve a turn. This is a human-managed operating rule, not a technical lock. LabNote provides no automatic queue, locking service or multi-agent write coordination. [Follow the deposit cycle and its failure/verification rules](lobby/ROUTINE_DEPOSIT_QUICKSTART.md).

A typical trail is **packet → response → review → decision**.

[See a fictional source-to-decision trail, including a corrected AI claim](docs/WORKED_CONTINUITY_TRAIL.md).
Expand Down Expand Up @@ -140,11 +144,14 @@ The rails do not make a model smarter, and they cannot make one infallible. They
LabNote itself needs:

- no daemon;
- no MCP server;
- no database;
- no hosted runtime;
- no repo-resident agent;
- no model API keys.

LabNote neither includes nor requires an MCP (Model Context Protocol) server. Your chosen assistant may use an external connector, including MCP, to access files or GitHub; that is the assistant's access route, not a LabNote service.

No shared-memory theatre.

Just ordinary files, clear routes and human-held authority. The ledger is right there in the files, where you can inspect it yourself.
Expand Down
2 changes: 2 additions & 0 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ No repository rename or LabNote identity-file edit should be required before fir

## 3. Operate LabNote

Follow the [routine deposit cycle](../lobby/ROUTINE_DEPOSIT_QUICKSTART.md) for each contribution below. Only one writer may deposit into a workspace at a time: the human authorizes the turn, waits for destination verification and the completion report, then authorizes the next. A visitor handle identifies a session; it does not reserve a turn. Reading and preparation may happen in parallel.

1. Copy `templates/datadrop_packet.md` for a new packet.
2. Fill in the packet header and task sections.
3. If the packet depends on larger files, add an operator-approved reference and a short summary instead of committing the raw dump.
Expand Down
33 changes: 28 additions & 5 deletions lobby/ROUTINE_DEPOSIT_QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,18 @@ Do not create a task branch for ordinary deposits.

Use a branch + PR only for procedure, policy, repo structure, code/script changes, cleanup, risky/bulky imports, many existing-file edits, or explicit human review.

## Human-Paced Deposit Cycle

One live workspace has one active writer at a time. People and agents may read and prepare material in parallel, but must not deposit simultaneously. The human coordinates turns across all people, sessions, tools and copies publishing to that workspace. A current-run visitor handle identifies a contributor; it is not write permission or a reserved turn. LabNote supplies no automatic queue or lock.

The cycle is: human authorizes this turn → contributor writes the complete deposit → verifies the agreed destination → reports completion → human authorizes the next turn. A failed, partial or unverified attempt must be resolved with the human before another writer starts.

## Quick Flow

1. Confirm that the expected LabNote structure is present and determine the current workspace context.
2. Confirm current-run visitor handle.
3. If no current-run visitor handle is supplied, stop and ask the human operator.
4. Use the default branch unless the operator explicitly names another branch.
4. Before any write, confirm with the human that this specific deposit is authorized and no other writer is active. If another writer is active or the turn is unclear, stop and ask. Confirm the destination—local, GitHub or both—and use the default branch unless the operator explicitly names another branch.
5. Register visitor if missing.
6. Check only relevant messages and notifications.
7. Read `lobby/TAGGING_PROTOCOL.md` if tags are needed.
Expand All @@ -34,12 +40,22 @@ Use a branch + PR only for procedure, policy, repo structure, code/script change
12. Add AI-generated tags as proposed JSON records only if useful.
13. Create packet, response, message, or signoff files.
14. Create JSON registry record files.
15. Do not edit generated CSV or `registry/INDEX.md` views manually.
16. Add a `README_FIRST` notice if team review or relay is needed.
17. Report files created and stop.
15. If team review or relay is needed, use messages/notifications and their JSON records under the existing routing rules. Do not edit `README_FIRST` as part of a routine direct deposit; lobby changes require branch + PR.
16. Regenerate required CSV and `registry/INDEX.md` views from the final canonical records using `scripts/generate_registry_views.py`; do not edit those views manually. If the available tools cannot do this, report the limitation and ask the human for help completing the deposit.
17. Complete and verify the whole deposit at the agreed destination as described below. Report its outcome and stop; do not start another deposit automatically.

The entrypoint, lobby front door, and visitor checklist are prerequisites for this quickstart; this file does not repeat them.

## Completion And Recovery

- A deposit includes its artifacts, required JSON records and any required regenerated views—not just the document. Before writing, inspect the current destination so prepared work is not applied over a stale copy.
- For local-only use, read back the files in the agreed local workspace and check that the records point to the intended artifacts and the required views are current. No remote push is required.
- For GitHub use, verify the files and records on the agreed remote repository and branch after publication. A draft, local commit or attempted push alone is not proof of remote completion. If both destinations were requested, verify and report each separately.
- Report any validation failures or pending/unavailable checks separately from file presence; do not call the deposit fully verified while required work or verification remains outstanding.
- If a write is rejected, interrupted or uncertain, preserve prepared work in its approved location. Tell the human what is confirmed present, what is missing or unverified, and what assistance is needed. Do not report success for a partial deposit.
- Before any human-authorized retry, inspect what landed and complete only the missing authorized work. Do not blindly replay a bundle, create duplicate records, overwrite another contribution, hand-merge generated views or force-push as recovery. If you cannot establish the destination state, stop and report that uncertainty.
- The human resolves an outstanding failed or uncertain turn before authorizing another writer. Neither a unique handle nor an apparently idle repository proves that the previous deposit completed.

## Canonical Naming

Use this pattern unless the operator supplies a better one:
Expand All @@ -66,13 +82,20 @@ responses/signoffs/<packet_id>-signoff.md

## Minimal Final Report To Operator

These are operator-facing report labels, not additional JSON registry fields.

```text
visitor_id:
intended destination(s):
deposit outcome:
verification evidence:
validation/check status:
missing or unverified work:
files created:
JSON registry records created:
messages checked:
notifications checked:
README_FIRST notice added:
review/relay message or notification paths:
relay/action needed:
signoff path:
stopped:
Expand Down
11 changes: 7 additions & 4 deletions lobby/VISITOR_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,14 @@ Do not create branches for ordinary datadrops, responses, messages, signoffs, or
0. Confirm that the expected LabNote structure is present and determine the current workspace context.
1. Confirm current-run visitor handle.
2. If no current-run visitor handle is supplied, stop and ask the human operator.
3. Use the default branch unless the operator explicitly names another branch.
4. Check only relevant messages and notifications.
5. Confirm the supplied source material belongs in this workspace.
6. Stop if routing, storage permission, binary handling, or registry path is unclear.
3. Confirm with the human that this specific deposit is authorized and no other writer is active in the same workspace. A handle identifies the session, not its writing turn. If another writer is active or the turn is unclear, stop and ask before any write, including visitor registration.
4. Confirm the intended destination: local workspace, GitHub repository or both. Use the default branch unless the operator explicitly names another branch.
5. Check only relevant messages and notifications.
6. Confirm the supplied source material belongs in this workspace.
7. Stop if routing, storage permission, binary handling, or registry path is unclear.

## Routine Deposit Flow

After the safety checks, follow `lobby/ROUTINE_DEPOSIT_QUICKSTART.md`.

The writing turn includes the entire deposit and destination verification. Report completion before the human authorizes the next writer; report a failed, partial or unverified result instead if completion cannot be confirmed.
10 changes: 10 additions & 0 deletions locales/zh-CN/AI_ENTRYPOINT.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,16 @@ AI 可以识别可能值得保留的材料,也可以说明或起草一项拟

以下情况必须使用 `branch + PR`:流程、政策、代码、仓库结构、清理、高风险/大体量导入、对大量现有文件的修改,或明确要求审阅的更改。

## 同一工作区每次只进行一项投递

LabNote 在同一个实际工作区中,一次只支持一位写入者进行写入。人和智能体可以并行阅读和准备材料;不支持同时投递,包括智能体群同时投递。共用工作区的人类操作者必须协调所有会话、工具以及向该工作区发布内容的副本的写入轮次。这是操作规则,不是强制执行的锁或自动队列。

由人类分配的本次运行访客会话标识用于识别会话;它既不授权投递,也不预留写入轮次。在进行任何写入(包括访客会话登记)之前,必须向人类确认:该项具体投递已获授权,且同一工作区当前没有其他写入者正在写入。如果有其他写入者正在写入,或轮次不明确,必须在写入前停止并向人类询问。不得仅凭唯一标识或仓库看似空闲就认定可以开始写入。

本轮写入涵盖整项已授权投递:其产物、必需的 JSON 记录以及需要重新生成的视图。在报告完成之前,必须在约定的目标位置——本地、GitHub 或两处——核验整项投递。草稿或本地提交不能证明已发布到 GitHub。

如果写入失败或结果不确定,应保留已准备的工作,报告失败、部分完成或未经核验的结果,并停止以等待人类指示。任何获授权的重试之前,都必须检查实际已落地的内容;不得盲目重放、覆盖相冲突的工作,或以强制推送作为恢复手段。在下一位写入者开始前,人类必须先解决尚未结束的本轮投递。遵循 `locales/zh-CN/lobby/ROUTINE_DEPOSIT_QUICKSTART.md` 中的完成与恢复步骤。

## 直接投递边界

直接常规投递仅限内容平面工作:其产物和基准记录可以写入 `datadrops/`、`responses/`、`messages/`、`notifications/`、`registry/packets/`、`registry/responses/`、`registry/messages/`、`registry/notifications/`、`registry/visits/`、`registry/visitors/` 和 `registry/tags/proposed/`。当 `scripts/generate_registry_views.py` 从同一次投递中新建或更改的基准记录生成视图时,也可写入生成视图 `registry/INDEX.md` 和 `registry/*_registry.csv`。
Expand Down
9 changes: 8 additions & 1 deletion locales/zh-CN/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

CapstanAI LabNote 是一个轻量级、基于文件的项目工作台账,适合在不同 AI 助手、编程智能体和独立聊天之间开展工作的人。它将经过选择的来源、交接、审阅、决策和下一步行动保存在普通 Markdown 文件和结构化 JSON 登记记录中,让下一次会话可以接续项目脉络。

由你决定哪些内容进入记录,以及哪些内容需要审阅。共享入口让每个 AI 都有清晰的阅读路径、明确的工作放置位置,以及等待人类作决定的停靠点。基本台账使用不需要 LabNote 后台服务、数据库或模型 API 密钥。
由你决定哪些内容进入记录,以及哪些内容需要审阅。共享入口让每个 AI 都有清晰的阅读路径、明确的工作放置位置,以及等待人类作决定的停靠点。基本台账使用不需要 LabNote 后台服务、MCP 服务器、数据库或模型 API 密钥。

CapstanAI LabNote 是这个独立工作台账的名称。它不依赖独立的 CapstanAI 服务或引擎即可使用。

Expand Down Expand Up @@ -103,6 +103,10 @@ registry/ ← 记录发生了什么、何时发生以及由谁完成

一个会话进入后,读取相关路径,完成自己需要贡献的部分,留下可追溯的记录,然后停止。人类始终掌握主导权。AI 可以建议哪些内容值得记录,但必须等待人类发起或批准这一步。

**同一工作区,每次只进行一项投递。** 人和 AI 智能体可以并行阅读、研究和准备材料,但不支持同时投递,包括智能体群同时投递。人类先授权一位贡献者进行投递,等待整项投递在指定的本地工作区、GitHub 仓库或两处均得到核验,并收到完成报告后,才授权下一次投递。共用工作区的人必须协调所有会话和工具的写入轮次。

由人类分配的贡献者标识用于识别会话;它不授予写入权限,也不预留写入轮次。这是由人执行的操作规则,不是技术锁。LabNote 不提供自动队列、锁定服务或多智能体写入协调机制。[参照投递周期及其失败处理和核验规则](lobby/ROUTINE_DEPOSIT_QUICKSTART.md)。

一条典型轨迹是 **packet → response → review → decision**;对应地,它是工作包(packet)→ 回复(response)→ 审阅(review)→ 决定(decision)。

[查看一条从来源到决定的虚构轨迹,其中包括对 AI 说法的修正](docs/WORKED_CONTINUITY_TRAIL.md)。
Expand Down Expand Up @@ -140,11 +144,14 @@ LabNote 不会把发生的一切自动保存下来。不是每条消息都应成
LabNote 本身不需要:

- 守护进程;
- MCP 服务器;
- 数据库;
- 托管运行时;
- 常驻仓库的智能体;
- 模型 API 密钥。

LabNote 既不包含也不要求 MCP(Model Context Protocol,模型上下文协议)服务器。你选择的助手可以使用外部连接器(包括 MCP)来访问文件或 GitHub;那是助手的访问方式,不是 LabNote 服务。

不演“共享记忆”这出戏。

只有普通文件、清晰路径,以及由人掌握的决定权。这份台账就在文件里,你可以自己检查。
Expand Down
2 changes: 2 additions & 0 deletions locales/zh-CN/docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ CapstanAI LabNote 分为三个阶段:获取副本、初始化(bootstrap)

## 3. 使用 LabNote

下方每项贡献都应遵循[常规投递周期](../lobby/ROUTINE_DEPOSIT_QUICKSTART.md)。同一工作区每次只允许一位写入者投递:人类授权本轮投递,等待目标位置核验及完成报告后,才授权下一轮。访客会话标识用于识别会话,不预留写入轮次。阅读和准备工作可以并行进行。

1. 复制 `locales/zh-CN/templates/datadrop_packet.md`,创建一个新的工作包(packet)。
2. 填写工作包头部字段和任务部分。字段名和状态值保持英文机器形式。
3. 如果工作包依赖较大的文件,请加入经过操作者批准的引用和简短摘要,而不要把整份原始材料直接提交进仓库。
Expand Down
Loading
Loading