08 Mar 15:34

MAC_OS_V1.1.0

7ff98db

Latest

如果使用默认配置，作图模型记得去掉 openai 前缀
figure_models: google/gemini-3-pro-image-preview
切记！！！其他供应商则无需改变 openai前缀

建议统一在设置中打开Command Execution Mode 的 System Terminal 选项，如果有 GUI或系统环境执行需求。

允许用户更改所有提示词，添加工具，装卸载 skills，更改内置的所有智能体结构和框架，思考步长，工具阶段步长，所有修改仅需更改配置文件（工具除外）。增加 fresh 工具，允许智能体的自我改进（动态刷新改进的提示词，工具和 skill进入执行过程）

支持 SDK。pip次项目后基于配置文件和简单的 sdk代码构建自己的 agent

InfiAgent Python SDK Guide

适用实现：

SDK: infiagent/sdk.py
用户目录路径: utils/user_paths.py
Task 运行时辅助: utils/task_runtime.py

1. 设计原则

当前 SDK 采用“实例描述运行时，方法绑定具体 task”的模型：

infiagent(...) 负责定义 runtime 配置
run(..., task_id=...) 和其他 task 方法负责操作具体任务

因此：

不再建议把 workspace 作为实例级主参数
task_id 才是任务主键，语义上就是任务工作目录绝对路径
run() 必须显式提供 task_id

2. `user_data_root` 规则

如果指定了 user_data_root，下面这些目录都会一起切换：

<user_data_root>/config
<user_data_root>/agent_library
<user_data_root>/tools_library
<user_data_root>/conversations
<user_data_root>/logs
<user_data_root>/runtime

其中：

share_context.json、stack.json、actions.json 都在 <user_data_root>/conversations
running task / fresh request 状态都在 <user_data_root>/runtime

例外：

skills 默认仍然走 ~/.agent/skills
只有显式传 skills_dir 才覆盖

3. 何时不需要再传路径参数

如果 user_data_root 里已经有完整内容：

config/llm_config.yaml
config/app_config.json
agent_library/...
tools_library/...

通常不需要再传：

llm_config_path
agent_library_dir
tools_dir

最小实例：

from infiagent import infiagent

agent = infiagent(
    user_data_root="/abs/path/to/my_root",
    default_agent_system="OpenCowork",
    default_agent_name="alpha_agent",
)

4. 常用初始化参数

agent = infiagent(
    user_data_root="/abs/path/to/my_root",
    llm_config_path="/abs/path/to/llm_config.yaml",
    agent_library_dir="/abs/path/to/agent_library",
    tools_dir="/abs/path/to/tools_library",
    skills_dir="/abs/path/to/skills",
    default_agent_system="OpenCowork",
    default_agent_name="alpha_agent",
    action_window_steps=12,
    thinking_interval=12,
    fresh_enabled=True,
    fresh_interval_sec=300,
    direct_tools=True,
)

参数语义：

user_data_root: 当前实例主数据根目录
llm_config_path: 覆盖模型配置
agent_library_dir: 覆盖 agent system 配置目录
tools_dir: 覆盖动态工具目录
skills_dir: 覆盖 skills 根目录
default_agent_system: 默认 agent system
default_agent_name: 默认根 agent 名称
action_window_steps: 动作窗口大小
thinking_interval: thinking 插入间隔
fresh_enabled / fresh_interval_sec: 定时 fresh 参数
direct_tools: 是否启用进程内 direct tools

5. 基本运行

from infiagent import infiagent

agent = infiagent(
    user_data_root="/abs/path/to/my_root",
    default_agent_system="OpenCowork",
    default_agent_name="alpha_agent",
)

result = agent.run(
    "请分析这个目录并给出重构建议",
    task_id="/abs/path/to/tasks/project_a",
)

关键点：

task_id 必填
run() 会先按 start.py 语义清理/归档必要状态
然后注册本次用户输入并在当前进程运行 executor

如果要明确重开任务：

agent.run(
    "重新开始这个任务",
    task_id="/abs/path/to/tasks/project_a",
    force_new=True,
)

6. Task 管理接口

6.1 `fresh`

agent.fresh(
    task_id="/abs/path/to/tasks/project_a",
    reason="reload runtime config",
)

行为：

task 正在运行：发定向 fresh 请求
task 未运行：重载配置后后台 resume

6.2 `add_message`

agent.add_message(
    "补充需求：保留已有结果，只做增量修改。",
    task_id="/abs/path/to/tasks/project_a",
    source="user",
    resume_if_needed=True,
)

行为：

追加到同一 task 的 current.instructions
不会当成新任务
运行中的 task 会在下一轮上下文重建时看到它
未运行 task 可按需后台恢复

6.3 `start_background_task`

agent.start_background_task(
    task_id="/abs/path/to/tasks/sub_task",
    user_input="后台整理日志并生成总结",
    force_new=True,
)

行为：

启动新的后台 Python 进程运行 start.py
日志写到 <user_data_root>/runtime/launched_tasks

6.4 `task_share_context_path`

agent.task_share_context_path(task_id="/abs/path/to/tasks/project_a")

share_context_path
stack_path

6.5 `list_task_ids`

agent.list_task_ids()
agent.list_task_ids(only_running=True)

返回当前 user_data_root 下已知 task 列表。

6.6 `task_snapshot`

snapshot = agent.task_snapshot(task_id="/abs/path/to/tasks/project_a")

running
share_context_path
stack_path
instruction_count
latest_instruction
history_count
last_updated
latest_thinking
latest_thinking_at
last_final_output
last_final_output_at

这个接口适合外部应用做面板和轻量 watchdog。

6.7 `reset_task`

agent.reset_task(
    task_id="/abs/path/to/tasks/project_a",
    reason="clear broken loop",
    preserve_history=True,
    kill_background_processes=True,
)

行为：

清空当前 current
清空 stack
可选归档到 history
可选尝试终止当前后台进程
删除该 task 对应的 *_actions.json

7. 运行时自省接口

7.1 `describe_runtime`

runtime = agent.describe_runtime()
print(runtime["user_data_root"])
print(runtime["agent_library_dir"])
print(runtime["tools_dir"])
print(runtime["skills_dir"])

关键字段：

user_data_root
config_dir
llm_config_path
agent_library_dir
tools_dir
skills_dir
conversations_dir
logs_dir
runtime_dir

7.2 `list_agent_systems`

systems = agent.list_agent_systems()
for item in systems["agent_systems"]:
    print(item["name"], item["path"])

适合外部调度应用决定使用哪个 agent system。

8. Tool Hooks

SDK 现在支持对任意工具调用注册前置/后置 hook。

适用场景：

记录工具审计日志
只监听 final_output
监听某些自定义工具的参数或结果
在工具调用前后触发外部状态同步

示例：

from infiagent import infiagent

agent = infiagent(
    user_data_root="/abs/path/to/my_root",
    tool_hooks=[
        {
            "name": "final-output-audit",
            "callback": "/abs/path/to/hooks.py:on_tool_event",
            "when": "after",
            "tool_names": ["final_output"],
            "include_arguments": True,
            "include_result": True,
            "argument_filters": ["status"],
            "result_filters": ["output", "status"],
        }
    ],
)

hook 字段：

name
callback: module:function 或 /abs/path.py:function
when: before / after / both
tool_names
include_arguments
include_result
argument_filters
result_filters

callback 接收的 payload 至少包含：

hook_name
when
tool_name
task_id
agent_id
agent_name
agent_level

注意：

hook 是 runtime 级能力，不是 CheapClaw 专属能力
如果系统存在子 agent，直接监听所有 final_output 可能会误触发；应结合 agent_level == 0 或更严格的工具/参数过滤自行约束
CheapClaw 当前默认不依赖 hook 更新 panel，而是依赖 task reconcile

9. 异步接口

这些接口都有 async 包装：

run_async
fresh_async
add_message_async
start_background_task_async
task_share_context_path_async
list_task_ids_async
describe_runtime_async
list_agent_systems_async
task_snapshot_async
reset_task_async

示例：

result = await agent.add_message_async(
    "补充一条要求",
    task_id="/abs/path/to/tasks/project_a",
)

10. 面向独立应用的建议

如果你要在独立项目里写 CheapClaw 这类应用，优先只依赖公开 SDK：

infiagent(...)
describe_runtime()
list_agent_systems()
run()
start_background_task()
add_message()
fresh()
task_snapshot()
reset_task()
tool_hooks

然后把应用层自己的：

panel store
social gateway
scheduler
watchdog
supervisor service
custom tools

都放在外部项目里。

11. 当前验证

已补充测试：

覆盖：

user_data_root 切换后路径是否统一
SDK 和原始 task 工具是否共享同一根目录语义
agent_library / tools_library 在自定义根目录下是否仍然可加载
不同 SDK 实例是否互不串用
后台任务日志是否落到 <user_data_root>/runtime/launched_tasks
CheapClaw 是否可以用公开 SDK 和动态工具目录独立运行
task_snapshot() 是否能从 share_context.history 回填完成态
tool hook 是否能在 final_output 后触发 callback

Assets 3

02 Mar 11:24

polyuiislab

MAC_OS_V1.0.1

0c873ee

MAC 客户端

修复滚动问题
日志问题（可以在～/mla-v3/log 文件夹下看到所有运行日志，用于提交异常或者自行排查问题。
增加系统终端权限选项（如果使用 mac-use 这种 gui 技能包，建议打开，并赋予终端录屏权限）
如下图设置即赋予infiagent 终端的所有权限。

Assets 3

09 Feb 10:38

polyuiislab

MAC_OS_V1.0.0

3b9e317

MAC APP V1.0.0

完全本地化，完全开源。
基于 infiagent 架构，支持长程任务。
支持不同智能体之间共享记忆，任务切换。
支持导入 skills，提供在线skills 库导入skills 到本地。

自带两个智能体系统
Cowork:
扁平架构智能体，支持装载 skills，单层智能体，支持广泛的通用任务，代码开发，桌面整理，深度调研，ppt 制作等等。

Default（research）：
支持全流程的学术研究辅助，绘图，调研，实验，文章生成。

使用方式：
下载安装包，点击 dmg，安装。
打开程序，点击设置，设置你的 api 和密钥：

或者也可以在raw yaml 中复制你以往的配置文件例如：
openrouter:

temperature: 0
max_tokens: 0
max_context_window: 500000
base_url: https://openrouter.ai/api/v1
api_key: 
timeout: 600              # LiteLLM 原生：建立连接及整体响应的最大等待时间 
stream_timeout: 30        # LiteLLM 原生：两个流式数据块之间的最大间隔时间
first_chunk_timeout: 30   # 应用层强制：连接建立+首包接收的最大时间（防止连接池死锁）
models:
- openai/google/gemini-3-flash-preview
figure_models:
- google/gemini-3-pro-image-preview
compressor_models:
- openai/google/gemini-3-flash-preview
read_figure_models:
- openai/google/gemini-3-flash-preview
hinking_models:
- openai/google/gemini-3-flash-preview

# 多模态配置
multimodal: true           # 主模型（models）+ thinking agent 是否支持多模态图片嵌入
compressor_multimodal: true   # 压缩模型（compressor_models）是否支持多模态图片嵌入

kimi:

temperature: 1
max_tokens: 0
max_context_window: 500000
base_url: https://api.moonshot.cn/v1
api_key: 
timeout: 600              # LiteLLM 原生：建立连接及整体响应的最大等待时间 
stream_timeout: 30        # LiteLLM 原生：两个流式数据块之间的最大间隔时间
first_chunk_timeout: 30   # 应用层强制：连接建立+首包接收的最大时间（防止连接池死锁）
models:
-  openai/kimi-k2.5
figure_models:
- google/gemini-3-pro-image-preview
compressor_models:
-  openai/kimi-k2.5
read_figure_models:
-  openai/kimi-k2.5
thinking_models:
- openai/kimi-k2.5 

# 多模态配置
multimodal: true           # 主模型（models）+ thinking agent 是否支持多模态图片嵌入
compressor_multimodal: true   # 压缩模型（compressor_models）是否支持多模态图片嵌入

选择agent_system和你的工作目录开始布置任务：

。

Assets 3

Releases: polyuiislab/infiAgent

完全模块化的智能体桌面端

InfiAgent Python SDK Guide

1. 设计原则

2. user_data_root 规则

3. 何时不需要再传路径参数

4. 常用初始化参数

5. 基本运行

6. Task 管理接口

6.1 fresh

6.2 add_message

6.3 start_background_task

6.4 task_share_context_path

6.5 list_task_ids

6.6 task_snapshot

6.7 reset_task

7. 运行时自省接口

7.1 describe_runtime

7.2 list_agent_systems

8. Tool Hooks

9. 异步接口

10. 面向独立应用的建议

11. 当前验证

Uh oh!

MAC 客户端

Uh oh!

MAC APP V1.0.0

Uh oh!

2. `user_data_root` 规则

6.1 `fresh`

6.2 `add_message`

6.3 `start_background_task`

6.4 `task_share_context_path`

6.5 `list_task_ids`

6.6 `task_snapshot`

6.7 `reset_task`

7.1 `describe_runtime`

7.2 `list_agent_systems`