MediaCrawler/mac-agent-os-main/archive_docs/matrix_docs/AGENT_INIT_GUIDE.md

AgentOS Agent Initialization Guide

Version: 1.0.0 | Updated: 2026-06-17
Purpose: Teach AI agents how to understand and operate this system correctly.
Scope: 3-machine federated system (chengzigedeAir / 5kechengdeAir / 7kecheng)

---

1. Identity Card

Field	Value
System	AgentOS — Federated AI Exoskeleton
Machines	chengzigedeAir (master), 5kechengdeAir (worker), 7kecheng (worker)
Connection	Tailscale mesh network (100.x.x.x)
Dashboard	Port 9988 on each machine, launchd auto-start
Git Repo	~/workbuddy-agent-os/agent-sync/ (synced to all 3 machines)

---

2. Python Environment (MOST IMPORTANT)

Never use system Python. The correct path is:

$HOME/.workbuddy/binaries/python/envs/agent-os/bin/python3

Or use the dynamic variable (for scripts):

$MC_PYTHON

Key packages installed:

• camoufox 0.4.11
• playwright 1.58.0
• uvicorn 0.46.0
• orjson 3.11.9

Common mistakes:

• ❌ python3 -m mc run → ⚠️ No module named mc (needs PYTHONPATH)
• ✅ cd $AGENT_SYNC/05_tools/07_matrix/scripts && $MC_PYTHON -m mc run ...
• ❌ Running pip install camoufox → Already installed in venv
• ❌ Using matrix nurture run → Legacy tool, use mc run instead

---

3. Command Architecture

User → Dashboard (port 9988)
  → /api/matrix/nurture/start         ← 养号执行入口
    → routes/matrix.py                  ← 自动选蓝图 + 路由到机器
      → 本机: subprocess mc run         ← 模式1
      → 远程: remote_exec exec_nurture  ← 模式2 (SSH)
        → mc run                        ← 真正的执行引擎
          → mc/engine.py                ← 身份分组 + 浏览器启动
            → cdp_connector.py          ← Camoufox 启动
              → matrix_modules/nurture/* ← 原子操作

Key commands for agents:

# 正确的养号执行（新路径，推荐）
cd $AGENT_SYNC/05_tools/07_matrix/scripts
$MC_PYTHON -m mc run --accounts=douyin_01 --blueprints=douyin_daily --rounds=10

# 查看账号列表
$MC_PYTHON -m mc account list

# 智能登录
$MC_PYTHON -m mc smart-login douyin_01

# 远程执行（通过 Dashboard API）
curl -X POST http://localhost:9988/api/federation/nurture \
  -H "Content-Type: application/json" \
  -d '{"machine":"7kecheng","accounts":["douyin_137"],"blueprints":["douyin_daily"],"rounds":10}'

---

4. Identity Directory Resolution

Directory naming: Identity dirs are named by phone number, NOT account ID:

identities/
├── phone_18550099569/        ← 身份目录（手机号命名）
│   ├── config.yaml
│   └── user_data/            ← 浏览器持久化数据
├── phone_15358497926/
│   ├── config.yaml
│   └── user_data/

Account-to-identity mapping: accounts.yaml links account IDs to identity dirs:

- id: douyin_136               # 账号 ID
  identity_dir: phone_18550099569   # 身份目录（映射关系）
  phone: '18550099569'
  platform: douyin
  owner_machine: 7kecheng        # 所属机器

How mc run resolves it (mc/engine.py:269):

# Step 1: Get identity_dir from account info
identity_dir = acct.get("identity_dir", acct["id"])  # → "phone_18550099569"

# Step 2: Strip "identities/" prefix if present
identity_dir = identity_dir.replace("identities/", "")  # → "phone_18550099569"

# Step 3: Resolve full path
full_path = IDENTITIES_ROOT / identity_dir  # → ~/.../identities/phone_18550099569/

❗ NEVER look for identities/{account_id}/. The directories are named by phone number.

---

5. Machine Routing & Blueprint Auto-Selection

Machine routing:

Each account has an owner_machine field. The API auto-routes:

• Local (owner_machine == this machine) → subprocess.Popen
• Remote (owner_machine != this machine) → SSH via remote_exec.py

Blueprint auto-selection:

Account Platform	Default Blueprint
douyin	douyin_daily
xiaohongshu	xhs_daily

---

6. Dashboard API

The Dashboard runs on each machine (port 9988, launchd auto-start on boot).

Key API endpoints:

Endpoint	Method	Description
/api/identity	GET	Returns this machine's identity
/api/machines	GET	Returns all machines' status
/api/matrix/accounts	GET	List all accounts (federated)
/api/matrix/nurture/start	POST	Execute nurture (see usage below)
/api/federation/nurture	POST	Remote nurture execution
/api/health	GET	Health check

/api/matrix/nurture/start request format:

{
  "accounts": ["douyin_01", "xhs_01"],
  "rounds": 10,
  "blueprint": "douyin_daily",        // optional, auto-detect if empty
  "machine": "7kecheng",              // optional, auto-route if empty
  "dry_run": true                     // preview only, don't execute
}

---

7. Common Pitfalls for AI Agents

Mistake	Why	Fix
Using python3	Wrong Python (no packages)	Use $MC_PYTHON or absolute venv path
Running matrix nurture run	Legacy CLI, doesn't handle identity mapping	Use mc run instead
Looking for identities/{account_id}/	Dirs named by phone number	Check accounts.yaml → identity_dir field
Using --dry-run flag	mc run doesn't support it	Use API's dry_run: true field instead
Installing packages with pip	Already in agent-os venv	Use $HOME/.workbuddy/binaries/python/envs/agent-os/bin/pip3 if needed
Running mc run from wrong directory	Module not found	Must cd to $AGENT_SYNC/05_tools/07_matrix/scripts first
Using CDP port 9222	Legacy Chrome, now uses Camoufox	Default: camoufox persistence mode

---

8. Quick Health Check

# Check Python venv
$HOME/.workbuddy/binaries/python/envs/agent-os/bin/python3 -c "from camoufox import AsyncCamoufox; print('OK')"

# Check mc CLI
PYTHONPATH=$AGENT_SYNC/05_tools/07_matrix/scripts $HOME/.workbuddy/binaries/python/envs/agent-os/bin/python3 -m mc --help

# Check Dashboard
curl -s --connect-timeout 3 http://localhost:9988/api/identity

# List accounts
PYTHONPATH=$AGENT_SYNC/05_tools/07_matrix/scripts $HOME/.workbuddy/binaries/python/envs/agent-os/bin/python3 -m mc account list

# Test nurture preview
curl -s -X POST http://localhost:9988/api/matrix/nurture/start \
  -H "Content-Type: application/json" \
  -d '{"accounts":["douyin_test"],"rounds":1,"dry_run":true}'

---

9. Environment Variables

Variable	Typical Value	Purpose
$AGENT_SYNC	~/workbuddy-agent-os/agent-sync	Synced git repo root
$AGENT_LOCAL	~/workbuddy-agent-os/agent-local	Local (gitignored) data
$MC_PYTHON	~/.../agent-os/bin/python3	Dynamic Python discovery
$HOME	/Users/chengzige (or 5kecheng/7kecheng)	Machine-specific home