Newshot

具备显式风险分析的 AI Agentic harness

Translation(model translation, not the source's own text)

Project Chaperone

论文:Project Chaperone: A Rule-Enforcing Harness for Proactive Assessment and Prevention of AI Agent Misconduct

Project Chaperone 是一个 harness,它允许 agentic AI 进行工具调用,同时强制执行高层策略,例如“任何个人数据都不得离开网络”。它增加了两项能力:

  • 运行前的审计报告会检查所有工作流中的每一条路径是否违反规则。由人类对规则的例外情况做出策略决策,这些批准会被记录下来。他们可以依据所需策略的“形态”来做出这些决策,而无需关心实际的工作流细节。(即“这个工作流想要把个人详细信息写入我的日历,这合理吗?”)
  • 运行时通过数据标签(UNTRUSTED、PERSONAL 等)和模块/工具属性(OUTPUT、LEAVES_NETWORK 等)来执行。所有调用在运行时都受规则约束(减去已确认的例外)。一个不值得通过设计规避的可能违规可以作为风险被接受:该调用仍然被禁止,如果某次运行尝试它,就会被拒绝。
漫画:运行前检查警告可能存在泄漏;标签在数据经过 LLM 时附着在数据上;一次试图通过电子邮件发送 PERSONAL 数据的调用被阻止
漫画:运行前检查警告可能存在泄漏;标签在数据经过 LLM 时附着在数据上;一次试图通过电子邮件发送 PERSONAL 数据的调用被阻止

漫画:Project Chaperone 背后的核心思想,简化为一条规则:PERSONAL 数据不得通过电子邮件离开。标签在数据经过 LLM 时随数据一起保留,harness 会阻止违反规则的那次调用。

Project Chaperone 解决了“带工具的 Agent”(灵活,但提示词无法强制执行规则)和硬编码工作流(可以分析,但分析是手动的,而且往往从未进行)的问题。在 Project Chaperone 中,这种分析是自动化的,并且规则在系统运行时得到执行。

本仓库附带五条共享规则(位于 examples/rules/default.yaml):无破坏性操作、任何内容不得离开网络、不输出个人或不可信数据、不得基于不可信数据(例如 LLM 写出的文本)做出决策。每个项目会添加若干显式例外。LLM 是可选的:模块可以调用一个 LLM,状态也可以让 LLM 选择工作流中的下一个状态。

本仓库还附带以下示例(部分在论文中提及)。其用意是展示一个工作流如何针对共享规则请求小型、有范围的例外:

  • deliveries - 智能地将邮件中的投递通知添加到你的日历。
  • share_notes - 一个展示有问题工作流的最小示例。
  • ask_my_mail - 一个 LLM 与电子邮件交互的示例
  • safe_rag - 就《联邦党人文集》或你自己的文档提问。

Install

执行以下一次性设置:


        git clone https://github.com/AppliedIngenuity-ai/project-chaperone.git
cd project-chaperone
# Set up your virtual environment here (see below)
pip install -e .
# (Optional): also install test libraries
pip install -e ".[test]"
      

设置 Python 虚拟环境有许多不同的方式,本仓库不限定具体方式。一个使用 venv 的示例可以是:运行一次 python -m venv .env,并在每个要运行下列命令的 shell 中执行一次 source .env/bin/activate。注意 pyproject.toml 要求 3.13 或更新版本,且 3.13.5 之前的版本尚未测试。

检查安装:


        python -m pytest
      

注意有 2 个测试被跳过,因为它们会请求一个真实的 LLM 服务器(参见下面的“Step 1: your LLM”)。

Run an example

在 project-chaperone 文件夹中:


        python -m chaperone run examples/deliveries
      
  • 你会看到一条 WARNING,提示 mail.send.* 模块未正确配置为发送邮件。这可以忽略。事实上,发送电子邮件的代码目前根本还没有写。

具备显式风险分析的 AI Agentic harness

  • 启动审计将会运行,并询问你项目正在请求的、针对 5 条默认规则的任何例外(通过 [examples/deliveries/exceptions.yaml]examples/deliveries/exceptions.yaml)。由于这是一个示例,你可以在每个提示处输入 1。最后,系统会要求你输入一个名称(只是为了让你记住自己为什么批准它)。这个带有名称的已批准例外列表会被添加到 state/deliveries/demo/accepted.json,因此相同的问题不会再被询问。请注意,这些批准是按示例限定作用范围的,因此“这对包裹追踪没问题”不会意外地为不相关的工作流制造漏洞。警告:在真实系统中,在允许例外之前,你会希望仔细检查细节并认真思考其影响。
  • 会启动一个本地 Web 服务器,并打印其地址,形式为 http://127.0.0.1:<port>/?token=<token>。在浏览器中打开该链接(必须运行在同一台机器上)。
  • 在该网页上,你会看到左侧有一个聊天区域,右侧有一个工作流列表。点击 assistant 工作流旁边的“Start”,该工作流的输出将出现在聊天区域中。在每个问题处输入任意内容。在 demo 配置中,我们用请求预定义工具调用的脚本替换了对 LLM 的调用:它会搜索邮件、询问地址(你可以输入任意地址),然后结束。随后该工作流允许你(通过复选框)批准它找到的任何发件人。
  • 接下来,点击 update_calendar 旁边的“Start”以启动该工作流。对话会显示读取到的每条虚构消息,以及每个条目的值。有一条消息是故意搁置的:它没有提供日期。README 详细说明了每个步骤。
  • 按 Ctrl-C 停止 harness Web 服务器。

你可以同时启动多个工作流,它们会在聊天输出中交错显示。

未来的运行不会重新询问你已批准的例外——直到你更改规则、例外、工作流或模块标签/属性:在这种情况下,启动审计可能会请求新的批准。

所有工作流状态都存储在 state/deliveries/demo/(或更一般地,state/<project>/<setup>/)中。你可以删除此文件夹,以忘记工作流在本地保存的所有内容。你也可以通过 Web UI 执行此操作:在 State 选项卡上,有一个“Start from nothing”按钮。请注意,通常只建议对演示数据删除此文件夹。

你可以传入 --setup 参数,在不同配置之间切换:默认的 --setup demo 使用虚构数据和伪造的工具调用。(也就是说,它不会与真实的邮件服务器或 LLM 通信)。它的所有状态都在文件夹 state/deliveries/demo 中,你可以通过删除该文件夹轻松重新开始。

你可以传入 --setup demo_llm,将假邮件传给真实的 LLM。(见下方配置)

或者,你可以使用 --setup real,在真实的日历、电子邮件和 LLM 上试用它。(这些必须配置,见下方“Use your own LLM, mail and calendar”。)在这种配置下,你应避免删除整个 state 文件夹,因为这会创建第二个日历。你可以改用 reset_all 工作流,它会清除大部分状态,但保留查找日历所需的有状态部分。

参见 docs/exceptions.md 了解例外和确认。

示例

有关更多细节,请参见每个示例的 ReadMe。有关文件如何组织,也请参见下方的“Project layout”。

deliveries

来自你邮件的投递通知,写入日历。由 LLM 选择对话的下一步;地址、勾选和批准都在不会传递给 LLM 的框中完成。

  • 试用:python -m chaperone run examples/deliveries(另请参见上方的“Run an example”)
  • 配置:demo、demo_llm、real_mail、real(见下方“Use your own LLM, mail and calendar”)。

文章标题:AI Agentic harness with explicit risk analysis

正文:

  • Workflows:assistant,一个对话,用于选择监控谁的邮件;discover_links,找出这些发件人跟踪链接的形式并询问使用哪一种;update_calendar,读取他们的新邮件并写入日历;reset_entries,删除条目并保留发件人;reset_all,删除所有已存储的内容。
  • 此外还有:prompts.yaml(LLM 的提示词)、modules/(每个工具一个文件)、demo/(虚构的邮件、LLM 回答和日历)。

share_notes

最小的示例:一条笔记、LLM 对它的摘要,展示给你,然后通过电子邮件发送。启动时报告该电子邮件可能违反规则 3 和 5:对每一项都回答 4(一个被确认的风险),当邮件被创建时,运行会拒绝发送它。

  • 试用:python -m chaperone run examples/share_notes
  • 配置:demo(虚构的回答,来自 demo/)。
  • Workflow:share_summary:总结一条笔记,展示摘要,然后尝试通过电子邮件发送它。

ask_my_mail

一个关键词和一个关于你邮件的问题;LLM 的回答连同其标签一起展示。

  • 试用:python -m chaperone run examples/ask_my_mail
  • 配置:demo(虚构的邮件和回答,来自 demo/)。
  • Workflow:ask_my_mail:在邮件中搜索该关键词,将消息和问题传给 LLM,展示回答。

safe_rag

关于《联邦党人文集》或你自己文档的问题。只有找到文档中的引文时才会展示回答。

  • 试用:python -m chaperone run examples/safe_rag(需要你自己的 LLM:见下文“第 1 步:你的 LLM”)
  • 配置:local(文集和你的 LLM)、arxiv(arXiv 摘要)、hosted(Claude)。
  • Workflows:single_pass,仅当逐字找到引文时才展示回答;multi_pass,当未找到时进行第二轮;answer,更简单的形式;typical_rag 和 just_ask_the_llm,用于对比,不做任何检查。
  • 此外还有:corpus/(85 篇文集)、prompts.yaml、questions.yaml 和 questions_compound.yaml(被测量的题目)、results.md(最近一次测量)。

除 demo 外的每个配置都需要你自己的 LLM、邮件或日历:下文“使用你自己的 LLM、邮件和日历”说明了如何操作。

更改配置

不要编辑随附的文件。把你的更改写在 private/local.yaml 中(git 会忽略 private/):该文件的键是随附文件的路径,映射到你需要更改的键,按照该文件的嵌套方式嵌套。

例如,要使用另一个地址的 LLM 服务器,把下面内容放进你的 private/local.yaml:


        configs/llm/local.yaml:
  api_base: http://localhost:8080/v1
      

一个文件容纳你所有的更改。一个更长的示例:


        # Your LLM server, and longer answers
configs/llm/local.yaml:
  api_base: http://localhost:8080/v1
  max_tokens: 8192

# deliveries, setup real: 7 days of mail, your time zone, the calendar's name
examples/deliveries/setups/real.yaml:
  tools:
    MAILBOX:         {client: {days: 7, timezone: Europe/Berlin}}
    GOOGLE_CALENDAR: {client: {timezone: Europe/Berlin, calendar_name: "My deliveries"}}
    CLOCK:           {client: {timezone: Europe/Berlin}}

# safe_rag, setup local: your own notes
examples/safe_rag/setups/local.yaml:
  tools: {DOCS_DB: {client: {folder: ~/notes, overview: "My notes on work and reading."}}}
      
  • 你可以更改的键就是随附文件拥有的键:打开它即可查看。
  • 如果你没有提到某个文件,或文件中的某个键,它会保留随附的值。你写的列表会整体替换随附的列表。
  • 注意,诸如你的邮件登录凭证之类的机密不在这里:它们在 private/env.sh 中(见下文第 2 步)。
  • 规则和例外不能以这种方式更改。

在下次启动时,从 project-chaperone 文件夹运行,程序会列出它读取到的更改:在询问规则之前列出的针对某个配置的更改,在询问之后、就在页面地址之前列出的针对 LLM 文件的更改。对于更长的示例以及 --setup demo_llm(它读取 LLM 文件,且不读取那两个配置中的任何一个):

标题:带有显式风险分析的 AI Agentic harness

正文:


        Configuration: 2 settings changed by private/local.yaml:
    configs/llm/local.yaml: api_base (private/local.yaml:3)
    configs/llm/local.yaml: max_tokens (private/local.yaml:4)
NOTE private/local.yaml: examples/deliveries/setups/real.yaml was not read by this run; nothing in it changed.
NOTE private/local.yaml: examples/safe_rag/setups/local.yaml was not read by this run; nothing in it changed.
      

添加一个杂散键(随附文件中并没有的键)不会改变任何东西。你会收到一个关于它的 WARNING。--defaults-only 会在一次运行中忽略你的本地改动;--config FILE 会读取另一个文件来代替 private/local.yaml。

使用你自己的 LLM、邮件和日历

三个步骤,按此顺序。每一步都向 deliveries 示例添加一个真实服务,并以一条展示其正常工作的命令结束。一个 setup 在它首次启动时被接受一次:在它询问的每条规则处输入 1,然后输入一个名称。

你的私有文件

你自己的登录信息放在 private/ 文件夹中,git 从不会提交它。其中没有任何内容是被随附的;每个文件都由你创建:

文件它的作用如何获得
private/env.sh当你运行 source private/env.sh 时,在你的 shell 中设置你的邮件登录信息(对于托管 LLM,还包括其密钥)。程序读取的是变量,从不读取该文件。从模板 private.example/env.sh 复制一次,然后填写(步骤 2)
private/local.yaml你对随附设置的改动:“更改配置”,见上文。由你编写
private/google_client_secret.json告诉 Google 是哪个程序在请求你的日历。从 Google Cloud 下载并重命名(步骤 3);没有模板
private/google_token.json你的 Google 登录信息。由 python -m chaperone signin 写入(步骤 3)

任何其他在扩展名之前以 _priv 结尾的文件,例如 configs/llm/local_priv.yaml,也不会被提交。

步骤 1:你的 LLM

要更改 LLM,请在 private/local.yaml 中更改 configs/llm/local.yaml(“更改配置”,见上文)。每个使用你的 LLM 的 setup 都会读取该文件,其中每一行都说明了它是什么。随附的、指向你的服务器的两行:


        model: "Qwen3.6-35B-A3B-MTP-UD-Q6_K_XL"     # the model's name, as your server calls it
api_base: http://localhost:8077/v1          # the server's address
      

服务器必须支持 OpenAI chat API。

llama.cpp(examples/safe_rag/results.md 中的测量使用了它,配合 Qwen3.6-35B-A3B):


        llama-server -m <your model>.gguf --port 8077
      

无需更改:local.yaml 已指向端口 8077。

Ollama(尚未在本项目中尝试):


        ollama pull qwen3
      

然后,在 private/local.yaml 中:


        configs/llm/local.yaml:
  model: "qwen3"
  api_base: http://localhost:11434/v1
      

另一台机器上的服务器:如果你的网络内,把它的地址放入 api_base。如果你的网络外(某个提供商、一台云机器),你的数据会发送到那里:还要为每个使用它运行的 setup 声明这一点(在 deliveries 中是工具 LOCAL_LLM,在 safe_rag 中是 LLM):


        examples/deliveries/setups/real.yaml:
  tools: {LOCAL_LLM: {facts: {LEAVES_NETWORK: true}}}
      

规则 NOTHING_LEAVES_NETWORK 然后在下次启动时报告它;回答 1 以允许它。该检查读取的是 setup 所声明的内容,而不是地址。

检查你的 LLM


        CHAPERONE_LIVE_LLM=configs/llm/local.yaml python -m pytest tests/test_llm_client.py
      
  • 17 passed:服务器有应答,并且模型选择了预期的步骤,并正确读取了编造的告示。
  • 任何提示 no answer from ... 的失败:api_base 中的地址没有任何应答。服务器在运行吗?其他失败是由此引发的。
  • 失败,且没有一条提示 no answer from:服务器有应答,但模型的回答不是预期的那些。较小的模型在页面上可能仍然可用,只是效果较差。

        python -m chaperone run examples/deliveries --setup demo_llm
      

文章标题:带有明确风险分析的AI Agentic harness

正文: 在页面上,点击 assistant 旁的 Start,然后输入 track my UPS packages。你的 LLM 决定接下来发生什么;邮件和日历仍然是虚构的。

第 2 步:你的邮件

程序通过 IMAP 以只读方式读取你的收件箱:它从不更改、移动或发送邮件。(Gmail:你已归档的邮件不再位于收件箱中,因此不会被读取。)

  • 在你的 Google 账户中,进入 Security → 开启两步验证(Google 要求下一步必须开启)。
  • 在 myaccount.google.com/apppasswords 创建应用专用密码:任意名称,例如 chaperone,然后点击 Create。Google 会显示一次 16 个字母;请保存好。(工作或学校账户可能不允许使用应用专用密码;这由其管理员决定。)
  • 复制模板(你已有的 private/env.sh 保持原样):mkdir -p private && [ -e private/env.sh ] || cp private.example/env.sh private/env.sh

复制模板(你已有的 private/env.sh 保持原样):


        mkdir -p private && [ -e private/env.sh ] || cp private.example/env.sh private/env.sh
      
  • 在 private/env.sh 中,填写标记为 FILL IN 的两行:你的 Gmail 地址,以及不带空格的 16 个字母。Gmail 服务器已经设置好了。

如果 Gmail 拒绝登录,请检查密码是否为应用专用密码,而不是你账户的密码。

Proton Mail:

  • 安装并启动 Proton Mail Bridge,登录你的账户。其窗口会显示 IMAP 端口和一个专为 bridge 生成的密码。
  • 复制模板:mkdir -p private && [ -e private/env.sh ] || cp private.example/env.sh private/env.sh

复制模板:


        mkdir -p private && [ -e private/env.sh ] || cp private.example/env.sh private/env.sh
      
  • 在 private/env.sh 中,填写标记为 FILL IN 的两行:你的地址,以及 bridge 的密码。然后移除 # Proton Mail Bridge 下五行开头的 #,如果 bridge 显示的端口不是 1143,则更改那里的端口。

然后,对于以上任一情况:

  • 如果你的时区不是纽约的:你日历上的日期和时间是按纽约时区取的。在 private/local.yaml 中,使用你所在时区的名称(来自此列表):examples/deliveries/setups/real_mail.yaml: tools: MAILBOX: {client: {timezone: Europe/Berlin}} CLOCK: {client: {timezone: Europe/Berlin}} 设置 real(第 3 步)有相同的两行以及 GOOGLE_CALENDAR 的:“Changing configurations” 展示了全部三个。

如果你的时区不是纽约的:你日历上的日期和时间是按纽约时区取的。在 private/local.yaml 中,使用你所在时区的名称(来自此列表):


        examples/deliveries/setups/real_mail.yaml:
  tools:
    MAILBOX: {client: {timezone: Europe/Berlin}}
    CLOCK:   {client: {timezone: Europe/Berlin}}
      

设置 real(第 3 步)有相同的两行以及 GOOGLE_CALENDAR 的:“Changing configurations” 展示了全部三个。

  • 在每个新终端中,运行之前:source private/env.sh

在每个新终端中,运行之前:


        source private/env.sh
      
  • 运行它:python -m chaperone run examples/deliveries --setup real_mail 在页面上:点击 assistant 旁的 Start,说出你收到其通知的承运商或商店(UPS 和 FedEx),勾选它找到的发件人,然后说 you are done。接着点击 update_calendar 旁的 Start。它读取来自这些发件人最近 21 天的邮件,最多 300 封,并写入日历文件 state/deliveries/real_mail/deliveries.ics,任何日历程序都能打开。

        python -m chaperone run examples/deliveries --setup real_mail
      

在页面上:点击 assistant 旁的 Start,说出你收到其通知的承运商或商店(UPS 和 FedEx),勾选它找到的发件人,然后说 you are done。接着点击 update_calendar 旁的 Start。它读取来自这些发件人最近 21 天的邮件,最多 300 封,并写入日历文件 state/deliveries/real_mail/deliveries.ics,任何日历程序都能打开。

文章标题:带有显式风险分析的 AI Agentic harness

正文: 只有带有 Authentication-Results 头、且其中写着 dkim=pass 或 dmarc=pass 的邮件才会被读取。这个头由你的邮件服务器添加,但发件人也可以自己写一个,所以它并不能证明邮件是谁发的(见下文“已知问题”)。实测运行使用的是 Proton Mail Bridge;Gmail 尚未在本项目中试用。

Step 3:Google Calendar

程序会在你的 Google 账号中创建一个属于它自己的日历,并且只往那里写入:Google 授予它的访问权限(calendar.app.created)只覆盖它创建的日历,不涉及其它任何内容。

一次操作,大约十分钟:

  • 在 console.cloud.google.com 登录并创建一个项目(名字随意)。个人 Gmail 账号即可;不需要结算信息。
  • APIs & Services → Library → 搜索 Google Calendar API → Enable。
  • APIs & Services → OAuth consent screen:应用名随意,填你的邮箱,受众选 External。然后 Audience → Test users → 添加你的 Google 账号。让它保持在 Testing 状态。
  • Clients → Create client → 类型选 Desktop app → Create。在打开的窗口中点击 Download JSON(现在就点,就在那个窗口里)。Google 会把文件命名为 client_secret_<numbers>.apps.googleusercontent.com.json;把它移动到程序查找的位置,并改成程序要的名字:mkdir -p private && mv ~/Downloads/client_secret_*.json private/google_client_secret.json(如果你是在另一台电脑上下载的,就把它复制到这个路径下。)文件里包含 Google 为你的项目生成的 client id 和 client secret;开头是 {"installed": {"client_id": .... 这个文件没有模板:只有 Google 给你的那个文件才管用。

Clients → Create client → 类型选 Desktop app → Create。在打开的窗口中点击 Download JSON(现在就点,就在那个窗口里)。Google 会把文件命名为 client_secret_<numbers>.apps.googleusercontent.com.json;把它移动到程序查找的位置,并改成程序要的名字:


        mkdir -p private && mv ~/Downloads/client_secret_*.json private/google_client_secret.json
      

(如果你是在另一台电脑上下载的,就把它复制到这个路径下。)文件里包含 Google 为你的项目生成的 client id 和 client secret;开头是 {"installed": {"client_id": .... 这个文件没有模板:只有 Google 给你的那个文件才管用。

  • 可选:日历名称,默认是 calendar_name: "Deliveries (agent)"。要修改它,以及修改时区(如果不是纽约时区):“更改配置”,见上文。
  • 登录:python -m chaperone signin examples/deliveries --setup real 打开它打印出的地址,选择你的账号并允许访问。随后 Google 会把浏览器重定向到 http://127.0.0.1:8765/。如果该页面无法加载(浏览器在另一台机器上),就从浏览器的地址栏复制完整地址,粘贴到终端里。登录信息会保存为 private/google_token.json。

        python -m chaperone signin examples/deliveries --setup real
      

打开它打印出的地址,选择你的账号并允许访问。随后 Google 会把浏览器重定向到 http://127.0.0.1:8765/。如果该页面无法加载(浏览器在另一台机器上),就从浏览器的地址栏复制完整地址,粘贴到终端里。登录信息会保存为 private/google_token.json。

然后,如同步骤 2:


        source private/env.sh
python -m chaperone run examples/deliveries --setup real
      

每个 setup 都保留自己的状态,所以要在 assistant 中重新选择发件人,然后 Start update_calendar。条目会出现在你 Google 账号的一个新日历“Deliveries (agent)”中,每个条目落在其包裹的日期上:最多往回查看三周。如果日历没有列出,请重新加载 Google Calendar 页面(Shift 加刷新)。

  • 每个状态文件夹各自创建一个日历。第二个(本文件夹的另一份副本,或 --state)会创建第二个同名日历。
  • 当 Google 项目处于 Testing 状态时,Google 会在七天后结束登录:请再次运行 signin 命令。
  • 要从 Google 中移除本程序的条目:Start reset_all。删除状态文件夹并不会移除它们。

改用托管 LLM(Claude)

文章标题:带显式风险分析的 AI Agentic harness

正文: 示例 safe_rag 有一个托管模式的设置:

  • 在 console.anthropic.com 上创建一个 API key。
  • 在 private/env.sh 中(第 2 步的复制命令会生成它),删除 export ANTHROPIC_API_KEY 前面的 #,并把你的 key 放在引号之间,使该行如下所示。然后运行 source private/env.sh。export ANTHROPIC_API_KEY="your key"

在 private/env.sh 中(第 2 步的复制命令会生成它),删除 export ANTHROPIC_API_KEY 前面的 #,并把你的 key 放在引号之间,使该行如下所示。然后运行 source private/env.sh。


        export ANTHROPIC_API_KEY="your key"
      
  • 运行它:python -m chaperone run examples/safe_rag --setup hosted 启动时,规则 NOTHING_LEAVES_NETWORK 会把 LLM 的调用报告为可能的违规:你的问题和文档的部分内容会发送到 Anthropic。回答 1 以允许它们。

        python -m chaperone run examples/safe_rag --setup hosted
      

启动时,规则 NOTHING_LEAVES_NETWORK 会把 LLM 的调用报告为可能的违规:你的问题和文档的部分内容会发送到 Anthropic。回答 1 以允许它们。

Commands


        python -m chaperone run    <project> [--setup NAME]   # the start's report and acceptance, then the page
python -m chaperone check  <project> [--setup NAME]   # the pre-run check only
python -m chaperone accept <project> [--setup NAME] --by NAME   # accept without the questions, for a script
python -m chaperone facts  <project> [--setup NAME]   # every module's facts
python -m chaperone signin <project> [--setup NAME]   # sign in to Google, for a setup whose calendar is Google's
      

当项目有 demo 时,--setup 为 demo,否则为 local。--state DIR 指定状态文件夹;默认是 state/<project>/<setup>。

Project layout

FileHolds
system.yaml标签,以及可能添加或删除每个标签的模块;profiles;stores;被拒绝的调用对一次运行的影响
setups/<name>.yaml工具(邮件服务器、LLM、页面)及其 facts;每个模块使用哪个工具
rules.yaml规则,以及它导入的规则文件( examples/rules/default.yaml ,五条共享规则)
exceptions.yaml规则的例外
workflows/<name>.yaml一个 workflow:它的状态、每次进行的调用,以及随后的状态
modules.py ,或 modules/模块:Python 函数,每个函数上方有一行声明它
ui.yaml页面为每个标签显示的文字和颜色

每个术语都在 docs/terminology.md 中定义;完整定义(代码按编号引用)在 docs/specification.md 中。

Known issues

  • 首次启动 deliveries 时,会在五条规则下列出 12 个例外,每个都回答 1。这是项目可能做什么的报告,而且很长。
  • 启动时不会尝试 LLM:没有服务器时,第一个需要它的调用会失败。“Check your LLM”(Step 1)会先尝试它。
  • 注意,大部分测试是在 Python 3.13.7 上进行的。
  • 每个状态文件夹都会创建自己的 Google 日历,因此两个文件夹可以同名。
  • 邮件检查读取的是发件人可以写入的头部(Step 2)。

所有这些,以及这些文档尚未涵盖的内容:docs/known-issues.md。

License

MIT,Copyright (c) 2026 Applied Ingenuity LLC。见 LICENSE。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗