scribe (Dpopsuev)

抄写员

AI代理的工作图。Scribe是一个具有原生DAG支持的结构化工件存储，它允许AI编码助手跨会话规划、跟踪和调用工作，超越了单个上下文窗口的限制。

快速开始

容器（推荐）

# podman or docker
podman run -d --name scribe \
  -p 8080:8080 \
  -v scribe-data:/data \
  quay.io/dpopsuev/scribe:v1.5.2

二进制

go install github.com/dpopsuev/scribe/cmd/scribe@latest
scribe serve                   # stdio (Cursor, Claude Desktop)
scribe serve --transport http  # Streamable HTTP on :8080

MCP配置

光标/克劳德桌面（stdio--本地二进制）：

{
  "mcpServers": {
    "scribe": {
      "command": "scribe",
      "args": ["serve"]
    }
  }
}

光标/克劳德桌面（HTTP--容器）：

{
  "mcpServers": {
    "scribe": {
      "url": "http://localhost:8080/?workspace=origami"
    }
  }
}

工作流程

Scribe是为自然语言而设计的。你和你的代理交谈，它会在幕后构建工作图。

你： 我想要v1.0的身份验证和速率限制。 代理人： 已经有了限速规范。我为auth创建了一个规范。你今天的目标是什么？

你： 我需要加强安全性——我们发现了一个令牌泄漏漏洞。 代理人： 我已经进行了一次审计，并为安全强化创建了一个目标。提交 BUG-1: Token leak你也想要一场竞选吗？

你： 对。 代理人： 活动准备就绪。这是审计和简报——3个任务，认证修复的规范，泄漏的bug，topo-sort显示执行顺序。先认证修复，然后限速，然后泄漏补丁。

你： 执行活动。 代理人： *（完成任务）* 安全强化行动完成。3个任务已关闭，代码已提交，所有测试均为绿色。

问题

LLM上下文窗口是有限的。一个编码代理可以在工作内存中保存大约10万个令牌。当一个会话结束时，它学到的一切——目标、决策、依赖关系、进度——都会消失。

这会产生三种故障模式：

1. 失忆症。 代理在每个会话中从头开始重新发现相同的代码库。
2. 漂移。 多届会议的工作失去了连贯性，因为没有关于决定内容和原因的共同记录。
3. 碎片化。 分散在聊天记录、markdown文件和问题跟踪器中的计划无法以图形形式查询或遍历。

Scribe通过为代理提供一个结构化的、持久的内存来解决这个问题，他们可以通过MCP工具进行读写——一个在可查询的DAG中存储活动、目标、规格、任务、错误及其关系的地方。

核心概念

人工制品关系

graph LR
    subgraph "Organizes Work"
        CAMPAIGN["campaign"]
        GOAL["goal"]
    end

    subgraph "Defines Work"
        SPEC["spec"]
        BUG["bug"]
        NEED["need"]
    end

    subgraph "Does Work"
        TASK["task"]
    end

    TEMPLATE["template"]

    CAMPAIGN -- parent_of --> GOAL
    GOAL -- parent_of --> TASK
    GOAL -- parent_of --> SPEC
    GOAL -- parent_of --> BUG
    TASK -- implements --> SPEC
    TASK -- implements --> BUG
    TASK -- depends_on --> TASK
    TASK -. follows .-> TASK
    NEED -. justifies .-> SPEC
    CAMPAIGN -. satisfies .-> TEMPLATE
    GOAL -. satisfies .-> TEMPLATE
    TASK -. satisfies .-> TEMPLATE
    SPEC -. satisfies .-> TEMPLATE
    BUG -. satisfies .-> TEMPLATE

活动 是将目标分组的任务容器。 目标 是北极星伪影，是规范、任务和bug的母体。 规格 和 漏洞 定义 *什么* 必须发生。 任务 实现规范并解决错误。 depends_on 边缘强制执行顺序； follows 边缘表示ROI顺序。这 detect 当任务没有spec/bug链接，或者spec/bug没有实现任务时，管理工具会发出警告。

工件图示例

graph TD
    CMP["SCR-CMP-1\nv1.0 Campaign\n(active)"]

    GOAL["SCR-GOL-1\nv1.0 Release\n(current)"]
    CMP -->|parent_of| GOAL

    SPEC["SCR-SPC-1\nAuth Spec\n(complete)"]
    GOAL -->|parent_of| SPEC

    BUG["SCR-BUG-1\nToken Leak\n(open)"]
    GOAL -->|parent_of| BUG

    TSK1["SCR-TSK-1\nImplement Auth\n(complete)"]
    TSK1 -.->|implements| SPEC
    GOAL -->|parent_of| TSK1

    TSK2["SCR-TSK-2\nRate Limiting\n(active)"]
    TSK2 -.->|depends_on| TSK1
    GOAL -->|parent_of| TSK2

    TSK3["SCR-TSK-3\nFix Token Leak\n(draft)"]
    TSK3 -.->|implements| BUG
    GOAL -->|parent_of| TSK3

实心箭头是 parent_of 边缘（树形结构）。虚线箭头是 implements, depends_on，或 follows 边缘（语义）。代理人使用 graph next 找到依赖项都已完成的最高优先级未阻塞任务。

建筑

生成的图表 轨迹 (locus diagram --theme natural).按健康状况着色的组件：绿色=健康，黄色=生病（粉丝人数>=3，流失人数>=8），红色=致命。

依赖图

locus diagram /path/to/scribe --type dependency --theme natural

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F7FAFC', 'primaryTextColor': '#2D3748', 'primaryBorderColor': '#4A90D9', 'lineColor': '#4A90D9', 'background': '#FFFFFF', 'fontSize': '14px'}}}%%
graph TD
    classDef boundary fill:#FFFFFF,stroke:#718096,color:#2D3748
    classDef component fill:#F7FAFC,stroke:#4A90D9,color:#2D3748
    classDef edge stroke:#4A90D9
    classDef entry fill:#4A90D9,stroke:#4A90D9,color:#FFFFFF
    classDef fatal fill:#E53E3E,stroke:#E53E3E,color:#FFFFFF
    classDef healthy fill:#38A169,stroke:#38A169,color:#FFFFFF
    classDef sick fill:#D69E2E,stroke:#D69E2E,color:#FFFFFF
    classDef violation_edge stroke:#E53E3E
    cmd_scribe["cmd/scribe [churn:12]"]:::entry
    config["config [churn:6]"]:::healthy
    directive["directive [churn:6]"]:::healthy
    keygen["keygen [churn:2]"]:::healthy
    lifecycle["lifecycle [churn:7]"]:::healthy
    mcp["mcp [churn:20]"]:::healthy
    mcpclient["mcpclient [churn:1]"]:::healthy
    model["model [churn:9]"]:::sick
    protocol["protocol [churn:14]"]:::sick
    render["render [churn:1]"]:::healthy
    store["store [churn:13]"]:::sick
    web["web [churn:6]"]:::healthy
    cmd_scribe -->|"13"| config
    cmd_scribe -->|"7"| directive
    cmd_scribe -->|"2"| mcp
    cmd_scribe -->|"6"| mcpclient
    cmd_scribe -->|"18"| model
    cmd_scribe -->|"90"| protocol
    cmd_scribe -->|"3"| render
    cmd_scribe -->|"6"| store
    cmd_scribe -->|"1"| web
    config -->|"2"| model
    config -->|"5"| protocol
    config -->|"1"| store
    lifecycle -->|"6"| model
    lifecycle -->|"6"| store
    mcp -->|"8"| directive
    mcp -->|"6"| mcpclient
    mcp -->|"9"| model
    mcp -->|"88"| protocol
    mcp -->|"3"| render
    mcp -->|"1"| store
    protocol -->|"1"| keygen
    protocol -->|"5"| lifecycle
    protocol -->|"57"| model
    protocol -->|"21"| store
    render -->|"24"| model
    store -->|"40"| model
    web -->|"2"| model
    web -->|"12"| protocol

层次图

locus diagram /path/to/scribe --type layers --theme natural

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F7FAFC', 'primaryTextColor': '#2D3748', 'primaryBorderColor': '#4A90D9', 'lineColor': '#4A90D9', 'background': '#FFFFFF', 'fontSize': '14px'}}}%%
block-beta
    columns 1
    block:layer_0["Layer 0"]
        cmd_scribe["cmd/scribe"]
    end
    columns 3
    block:layer_1["Layer 1"]
        config["config"]
        mcp["mcp"]
        web["web"]
    end
    columns 4
    block:layer_2["Layer 2"]
        directive["directive"]
        mcpclient["mcpclient"]
        protocol["protocol"]
        render["render"]
    end
    columns 2
    block:layer_3["Layer 3"]
        keygen["keygen"]
        lifecycle["lifecycle"]
    end
    columns 1
    block:layer_4["Layer 4"]
        store["store"]
    end
    columns 1
    block:layer_5["Layer 5"]
        model["model"]
    end

包裹

存储

单一SQLite数据库（CGo免费通过 modernc.org/sqlite).桌子：

• 人工制品 --UID主键（加密/随机十六进制），人类可读的ID作为唯一索引，碰撞时自动重命名。JSON用于数组/映射。
• 边缘 --有向图： (from, to, relation) 具有独特的约束。
• 序列 / scoped_sequences --带有碰撞检查的自动递增计数器。

快照：使用可插拔后端（本地文件系统，未来的S3）进行自动定期备份。通过预还原备份进行还原 admin snapshot restore.

默认位置： ~/.scribe/scribe.sqlite （二进制）或 /data/scribe.sqlite （集装箱）。

数据模型

每件艺术品都带有：

• 身份： 自动生成的ID(PREFIX-YYYY-SEQ)、种类、范围
• 内容： 标题、目标陈述、命名部分（任意文本块）
• 图表： 父级、依赖边、类型化链接（证明、实现、文档）
• 生命周期： 状态、优先级、冲刺分配、标签、时间戳
• 扩展名： extra 域特定键值对的映射（提醒、自定义字段）

词汇表被强制执行：未知类型被拒绝，并提示通过以下方式注册它们 scribe vocab add.未知字段进入 extra.

MCP工具

配置

Scribe使用零配置。要进行自定义，请创建 scribe.yaml:

# scribe.yaml
db: ~/.scribe/scribe.sqlite
transport: stdio
addr: ":8080"

scopes:
  - myproject

vocabulary:
  kinds:
    - goal
    - sprint
    - task
    - spec
    - bug
    # add your own via: scribe vocab add 

schema:
  kinds:
    goal:          { prefix: GOAL }
    sprint:        { prefix: SPR }
    task:          { prefix: TASK }
    spec:          { prefix: SPE }
    bug:           { prefix: BUG }
    campaign:      { prefix: CON }
    template:      { prefix: TPL }
    need:          { prefix: NED }

  statuses:
    - draft
    - active
    - current
    - complete
    - dismissed
    - archived

  guards:
    archived_readonly: true
    completion_requires_children_complete: true
    auto_archive_goal_on_justify_complete: true
    delete_requires_archived: true
    auto_complete_parent_on_children_terminal: true
    auto_activate_next_draft_sprint: true

workspaces:
  origami: [origami, asterisk, achilles]
  sidecar: [scribe, locus, lex, limes]

解决顺序： --config 旗帜> $SCRIBE_CONFIG > ./scribe.yaml > $SCRIBE_ROOT/scribe.yaml > ~/.scribe/scribe.yaml >内置默认值。

超控链： CLI标志>环境变量>配置文件>默认值。

工作区连接（HTTP）： 添加 ?workspace=origami 指向MCP URL以限定到特定范围的连接。

对于容器，请在以下位置挂载配置文件 /data/scribe.yaml:

podman run -d --name scribe \
  -p 8080:8080 \
  -v scribe-data:/data \
  -v ./scribe.yaml:/data/scribe.yaml \
  quay.io/dpopsuev/scribe:v1.5.2

环境变量

许可证

麻省理工学院