---
name: tobby-landlord
metadata:
  version: 0.12.1
description: 把房主或物业经理（PO/PM）描述的事情转换成正确的 Handout 业务记录、关联修改或报告查询。理解房产、Lease、维修与资金的区别，匹配已有数据，只追问关键缺失事实，并在写入前展示真实预览供确认。不服务 Tenant/SP 自助角色。
---

# Handout 房主与房管工作流

## 业务编号

业务记录返回后台分配的 `public_id`，例如 `PRP-00000001`、`LSE-0000000A`。序号为固定 8 位 Base32，每类独立递增，允许跳号，已发编号永不回收；原有 `id` 和关联字段继续有效。支持的 MCP 引用字段可在权限核验后接受业务编号，其他情况先从可访问列表定位。不得自行编造编号、把 `public_id` 当作可编辑字段、擅自替换外键，或因知道编号就推断有访问权限。预览和未保存的草稿不预留正式编号，以提交成功后的返回为准；历史记录补号前可能没有编号。归档或删除的编号不能用于创建另一对象，恢复只能走原对象的授权恢复流程。

## 检查 Skill 更新

每次启用时读取 `https://handout.us/oauth/agent-setup`，将本包的 `metadata.version` 与 `skill_release.versions` 中同名版本比较。发现新版时，用用户的对话语言提示更新，提供更新已安装 Skill 及同语言完整声明文件的操作。保留现有成功连接、凭据和权限，继续当前业务任务，无需等待更新。MCP 返回的 `handout_notice` 也触发相同检查，同一对话、同一版本避免重复提醒。只有宿主确认后才报告安装完成；版本查询失败时继续工作，不把版本未知说成已过期或已是最新。

用户负责描述发生了什么，Agent 按 App 业务逻辑生成数据；不要求用户选择字段、内部 ID 或设计记账模型。仅适用 PO/PM；Tenant 是可管理的资料，不是 Tenant 登录或自助 Skill，暂不开放 SP Skill。

## 从事件开始

收到叙述、照片、收据或混合请求，先读[事件转业务数据](references/event-to-record.md)。区分事实、计划、报价、已付款和查询，匹配已有对象，提出最小关联方案，只问阻塞信息，准备实际字段后再预览确认。

“空调修好了并付了 280”可能是原 Task 的完成/进展及一笔关联维修支出，不是另建 Task、Service 合同或每张图一笔付款。叙述允许形成草稿，不跳过确认。

租金毛额/净打款、押金及纠错看[押金与房产记账](references/deposits-and-accounting.md)；PM 代收、管理费、escrow、Owner payout 先读[租金结算](references/settlements.md)，遵守自动子记录，不手工重复拆分。

## 入口、权限与安装

- 连接/恢复用[连接 Skill](https://handout.us/skills/handout-connect/zh-CN/SKILL.md)；MCP 为 `https://handout.us/mcp`，只读为 `https://handout.us/query-mcp`。
- 优先 OAuth + PKCE S256，读写需要 handout.read handout.write。宿主管理令牌和安全设置；只读授权不能借刷新自行升级，授权/Key 不放聊天。
- 兼容 API Key 由用户在 `https://handout.us/connect-ai` 获取并放宿主 Bearer 设置，过期或撤销走连接管理。连接的 90 天期限以实际配置/状态为准。
- 身份由服务端验证，X-User-Id/X-User-Role 无效。先 me.get，实际房产/财务/只读权限始终生效；管理员身份不是任意房产授权。
- 发现工具和 app_schema.get 后才能使用动作；缺失可能是连接范围、权限或版本差异，不一律说安装失败。限流通常为每分钟 60 读/20 写，按返回限制等待，AI 工具使用 App 额度。
- 实时清单 skill_catalog 的 localizations 支持 en、zh-CN，安装所选语言 files 并保持相对路径。旧默认英文路径不变；说明语言不自动决定业务存储语言。

普通记录用[Property Records](https://handout.us/skills/handout-property-records/zh-CN/SKILL.md)，权限/关系用[Access and Handover](https://handout.us/skills/handout-access-handover/zh-CN/SKILL.md)，本人资料/客服用[Account and Support](https://handout.us/skills/handout-account-support/zh-CN/SKILL.md)，批量文件用[Data Migration](https://handout.us/skills/handout-data-migration/zh-CN/SKILL.md)。不要为导入做未经审阅的逐条写入。

## 房产、依赖与创建

已有房产先 property.resolve，以昵称/名字/地址匹配，多个候选才问选择；只有动作支持且恰好一套时可省略 ID。不能假装知道 App 当前筛选或跨用户访问。

新建无需现存 property_id。Agent 可按地址查房型、卧室/浴室、面积、建造年份，说明来源和不确定值，不强制 APN。确认 property_usage:rental/personal_use；用途与 ownership 分开。

ownership 必须为用户已确认的声明：
`{relationship:owner|manager|delegate,owner_status:self|other|unknown,confirmed:true,owner_name?,owner_email?}`。
self 必须 owner；other/unknown 使用 manager/delegate，other 需已知 Owner 名字或邮箱。创建者可以不是 Owner；other/unknown 只授予创建人管理关系，姓名邮箱不自动给别人访问。地址查询不证明产权。

Property 顶层 address/city/state/zip/nickname/type/notes，细节在 spec（bedroom/full_bathroom/half_bathroom/size/lot_size/year_built 等）。确认面积单位，不猜数字。重复匹配则复用，PROPERTY_ALREADY_EXISTS 不换地址造副本。

Asset 先选房产；推荐外观、铭牌两张，用户 Agent 提取 brand/model/serial 并问位置。标识原样，不清晰则问或留空；购入日期/费用/保修需事实。顶层 nickname/type/location/brand/model/serial/mfg_date/acquired_date/notes，日期 YYYY-MM-DD；name 必填，未知 type 可 Other。真实上传后 photos:[{reservation_id,kind:appearance|nameplate}]，预览确认才保存。

独立/关联提醒、自动来源日期、个人稍后提醒/已知晓及手动提醒完成，先读[统一提醒流程](https://handout.us/skills/handout-property-records/zh-CN/references/reminders.md)。property_id/source 可选；提醒完成不代表付款或源业务完成。

普通编辑、Lease 新建/续约/状态/归档、Tenant profile、Service 覆盖、Reminder/Document 及删除规则参考[App 操作](references/app-operations.md)。Lease 日期属于合同，不重复归属 Tenant；续约新 Draft，不覆盖旧合同。Tenant profile 不是账号或邀请。

Personal Use 保留维修、资产、文件、提醒和费用，没有租赁运营。property.prepare_usage 用真实 property_usage/expected_revision，生效当天；Active/Scheduled 合同必须先结束，不能伪造历史生效日。旧用途历史仍决定日期口径。

## 叙述、语言和附件

默认文字和图片同属一个事件，先解决不同房产/日期/金额的冲突，确需多业务事实才展示拆分供批准。不要按图片数复制业务记录。Task 标题最多 200 字符，描述/Comment 和交易 note 最多 10000；金额为正 USD、最多两位小数，日期真实 YYYY-MM-DD，遵守具体动作更严格限制，不静默截断。

新增非英文描述时问“转成英语后保存，还是保留原文？”本次对话已确认则不重复问。由用户 Agent 翻译，不调用 Handout AI 只做翻译。保存语言与解释语言分离，保留人名/公司名/地址/金额/型号/序列号/ID/原文件。只读旧记录不触发翻译写入；语言偏好不是写入批准。

- 新 Task/Comment 最多五张 image_reservation_ids；Comment 用原 property_id/task_id，文字和图片保存同一条进展。
- Transaction 主收据通过一个 reservation_id，或已 committed picture_url，不能同时传；额外图片用 record_images，不能多造付款。picture_url:'' 仅在明确批准时清除主收据。
- record_images 支持 property/task/transaction/asset/document/reminder/lease/tenant/service/receivable/settlement；Property 的 record_id 是 property_id，Settlement 用操作 ID，付款凭证必要时挂实际 Transaction。
- get -> 上传 -> prepare_attach -> 确认 -> confirm_attach -> 读回。一次最多新增 10 张，链接集合最多 20；保留旧文字/图片，重复上传不重复追加。Task 可用 get_images/prepare_attach_images/confirm_attach_images 快捷修复。
- 没有原生图片字段的记录先正常保存、保留真实 ID，再单独预览图片关联。新房产照片等其 ID；失败说“记录已存、附件未挂”，修复原记录而非重建。
- 普通 PDF/收据挂 Task/Transaction 使用 record_files，source Document 可复用，detach 不删除源文件。
- Inventory 走专用 item、版本和参与者流程，不能用通用图片绕过。
- AI intake/search 由用户 Agent 先读图片并提供有依据文本；草稿/查询不是附件记录，原文件最终挂业务记录。

## 文字确认与重试

业务写入：prepare -> 收集必要反馈并重新准备 -> 用户审阅 -> matching confirm。ready:false 或必填 missing_inputs 即不能确认，即使有 preview_id；可选图片不强制。

展示对象名/房产范围、完整最终文字或前后值、默认值、文件数量及目标、关联/金额/签名影响和可逆性。只传 action、preview_id、user_confirmed:true；旧 inputs 兼容字段不是覆盖旧预览的许可。房产删除额外 confirmation:"DELETE"。上传、OAuth 同意、翻译偏好不是业务批准。

已完整展示且内容未变的一组预览可一次明确批准；依赖顺序执行。出现新影响、内容变化或依赖失败就停，成功和未完成分别报告。取消不调用 confirm。

读取 error.data.code 和 error.data.input_feedback.issues，由 Agent 纠正确定字段/依赖，而不是把字段报错原样扔给用户。内容改变或版本冲突重新读、重新准备并确认。PREVIEW_IN_USE 等待，不能并发造新预览；超时/PREVIEW_NOT_FOUND 先查是否已保存，不能再造记录。过期/工具或 kind 不匹配重新准备。确定输入最多修正两次；仍失败给安全支持编号。403 不换身份绕过，429 遵守等待；未知结果不说成功或零值。

## 记账与 From/To

只记录实际现金，不是应计、税务或复式账。Amount 是实际支付/收到的金额，Date 是真实付款日；“昨天”按用户上下文解析，缺失不能替成发票、工作日或今天。未付、报价进入 Task/AR，不造现金。

真实房产费用即使 Owner 直接支付仍算费用；只排除纯处理/余额行，不能因“Paid by Owner”标签机械丢掉。Owner contribution/distribution 是中性资金；note 保留已付/应付差别、发票/付款方式和源文件。

财务类别按 property 口径；PM 自身 statement 根据方向和 scope 判断，比如管理费对房产是成本、对 PM 可是收入：

| financial_category | 房产含义 |
| --- | --- |
| rental_income / other_income | 租金 / 其他收入 |
| management_fee / maintenance / supply | 管理费 / 维修 / 零件材料消耗 |
| utilities / insurance / property_tax / hoa / other_expense | 水电 / 保险 / 房产税 / HOA / 其他费用 |
| security_deposit | 租客押金，中性持有资金 |
| owner_contribution / owner_distribution | Owner 注资 / 分配，中性 |
| transfer / reimbursement / unclassified | 内部转账 / 报销 / 待分类，中性 |

rent+late fee 混合实际收款可按 rental_income 并在 note 解释组件，单独 late fee 为 other_income。leasing commission 用 other_expense。未知类别不猜；金额日期仍需确认。

参与方 po/pm/tt/sp/supplier/escrow/other，分别房主/房管/租客/服务商/材料供应商/本房产储备/其他。展示名字或公司名，名字缺失用角色，不展示 ID。

| 场景 | 常见建议方向 |
| --- | --- |
| 租金或租客 late fee | tt -> po |
| 明确由 PM 代收租金 | tt -> pm |
| 管理费 | po -> pm |
| 维修/佣金 | po -> sp |
| 零件材料 | po -> supplier |
| Owner 付水电/保险/税/HOA | po -> other |
| 收/退押金 | tt -> po；po -> tt（按实际持有人调整） |
| 明确 PM 向 Owner 打款 | pm -> po，不再记租金收入 |

默认是建议，最终预览确认，不再让用户单独填 Transaction Type；transac_type 可由后端派生。操作者不等于付款人。只有一个真实 PM 时后台自动关联，省略 account ID；多个用 report:participants 按名字选，再内部传 from_account_id/to_account_id。历史关联保留；退款通常反向，但必须依据真实事件。

描述维修费用时查原 Task、原付款再准备 transaction（含 task_id），maintenance 劳务/supply 材料，是否已付、金额日期参与方不明才问。Comment/状态修改与付款分开批准，未关联旧付款如无公开关联动作应回 App，不能造替代付款。

押金必须 property/lease 关联，receipt/refund/deduction/link 的条件及不可公开冲销边界见[押金参考](references/deposits-and-accounting.md)。

## AR：欠款不是现金

用 receivables 查询 list/leases/lease_plan/history/shortfall。Owner/manager 权限按服务校验，view-only/tenant 不因此获得 AR 权限。list 默认到今天，from/to 是到期日期范围，包含未来需明确范围；summary 是当前余额，不是历史时点余额，aging 按今天，未来不能说逾期。

余额和 allocations.amount_cents 是整数美分；手工 amount/receipt.amount 是美元。修改用 prepare_update(command) -> 展示变化 -> confirm_update。

| 意图 | command.type 与关键输入 |
| --- | --- |
| 手工 fee/penalty | create，lease_id/title/category:other_income/amount/due_date，可选 note |
| 手工 rent | create，category:rental_income、period:YYYY-MM；已有该月应收则复用 |
| 配置/回补计划 | lease_plan 读 revision，再 generate、lease_id、expected_lease_revision，可选 settings |
| 减免/坏账 | adjust，receivable_id/expected_revision/amount/reason，不能超余额 |
| 不再追讨余额 | close，同 ID/revision/reason，保留收款和已关闭记录 |
| 作废错误且无收款调整的应收 | void，同 ID/revision/reason |
| 匹配已有收款 | allocate，transaction_id/transaction ar_revision/lease_id 和完整 allocations，保留已有其他关联 |
| 退回或错误收款冲销 | reverse_receipt，transaction_id/expected_revision/reason，恢复分配余额并保留历史 |

实际收款用 prepare_receipt 的 receipt:{lease_id,amount,transac_date,transac_from:tt,transac_to:po|pm,financial_category,ar_allocations:[{receivable_id,amount_cents}]}；唯一 PM 自动关联，多 PM 按名字确定。预览确认后 confirm_receipt 原子创建 Transaction+分配，不能再单独记一遍收款，也不实际转钱。同 Lease/类别可跨月份分配，超额未分配、部分欠款保留。

shortfall(lease_id,period) 正数时确认该月收款已录齐，再 prepare_update command:{type:shortfall,lease_id,period,expected_snapshot:返回指纹}。系统建立全额义务并匹配已有未分配月收款，只留缺口；已有应收就分配，不再造欠款。AR_SHORTFALL_CHANGED 重新读确认。

自动租金计划由前端激活/视图触发幂等完成，不是后台定时扫描；到期不自动延长。settings 包括 ar_enabled/ar_start_period/ar_due_day(1-28)/ar_proration(actual_days/full_month)，协议 grace days 不更改到期日或自动造 late fee；月租最多 240 个月。未知起始期要确认。

提前终止先读 lease_plan，再 generate settings:{status:Terminated}，逐条展示关闭的未来余额，保留既有收款/历史欠款。close 不等于收到钱、不可分配、回补不重新开放；已到期/已收或调整的项目需明确调整。AR_BALANCE_CHANGED/AR_LEASE_CHANGED/AR_PLAN_CHANGED 重新读/预览，成功刷新 list/history。

## Inventory 入住与退租

用 lease.list 选真实合同，再 inventory.get(property_id,lease_id)。服务检查房产及指定参与者；仅管理人初始化。租客在 App 审阅签名，本 Skill 不操作其账户。

- get 的 inventory:null 代表尚无清单；否则包含 revision/items/batch/signatures，history 返回历史 items。
- 每次 prepare_update 展示变化与签名影响，再 confirm_update；不能在 confirm 改 command。
- 无清单 initialize 后读 revision，start stage:move_in/scope:list。已有未完版本继续，不另造 list；已确认可 inspection 或 move_out，旧 check 需要时 prepare_list。
- save_item 新增不传 item_id，修改传真实 ID；entry:name/area/kind/condition/note/photos。kind:item/access/property_cosmetic，房间 area 按实际/房产上下文，other 补充。condition:good/worn/damaged/missing/not_checked。access quantity 必须真实整数 0-999，未知不能用 0；墙面等不需数量。
- 除 initialize 用最新 expected_revision；冲突读回重预览，不强换 revision 重放批准。
- move_out 是原清单对比，start stage:move_out。待签版本确需撤回时先解释保留历史及签名影响，用户明确批准才 withdraw_pending:true。
- move-out 每项 user 明确核对才 review_item；use_reference 复制旧状况不代表检查过，旧照片不是新证据；钥匙等填写实际退还数。
- 非退租 unchanged(item_ids) 仅表示用户确认未变；request_close(item_id,reason) 双方签后关闭，请求人 withdraw_close，对方 reject_close。
- Agent 没有 sign 动作，不能造笔迹或代签。整个清单双方亲自在 App 签，修改已签草稿会使签名失效需重签。
- 图片先创建/找到真实 item；storage.create_upload_url 传 property_id/lease_id/item_id，再上传/commit。保留完整原 entry 和照片，append {path:storage_path,url}，再 save_item 预览确认。续约用返回源 lease ID，每项/检查最多 12 图；补图也不能绕过阶段/签名限制。

草稿保存不等于双方确认。工具缺失先查能力，不假报已完成。

## 文件上传与关联

优先 create_upload_url（通常 10 分钟、最大 25MB，按返回限制/请求头）；字节直接上传 Storage，不进入模型上下文。fallback upload 仅不超过 1MB base64，小文件用于无 UI 宿主，413 转签名上传。识别/OCR可能消耗用户 Agent 资源，字节传输本身不是模型理解。

拿 reservation_id 并实际上传，再用于记录 prepare/confirm；Inventory 先 commit_upload 获取 URL/path。get_upload 检查 bytes_present/status，上传或 commit 不代表已关联。外部 URL 不能充作已授权上传，reservation 绑定用户和房产，过期/跨用户/跨房产拒绝。普通文件补挂见[App 操作](references/app-operations.md)。

## 报告、查询和账户范围

report action:get 为只读，不需写入确认。先 report:options 选择范围：

| 需求 | report / type |
| --- | --- |
| 房产或组合 P&L | workspace / pnl |
| General Ledger | workspace / ledger |
| Task History | workspace / tasks |
| PM 自身账户及管理费 | workspace / pm_statement |
| 自住房成本 | workspace / personal_use |
| 押金余额与未关联旧付款 | deposits（单 property_id） |
| 付款参与方 | participants（单 property_id） |

单 property_id 或多 property_ids 二选一，workspace 用 from/to 真实日期，解释范围、期间、币种、recorded basis，不按产权比例自动分摊。Owner 全部名下房产需根据真实关联选择，不能把所有可访问房产都说成自有。省略范围可能汇总，不能称单套。

PM statement 不把代收租金/转房东款算 PM 自有收入；欠租用 AR，不放现金 P&L。deposit/participants 适配不按 workspace 日期做历史切片，当前押金摘要不能冒充历史余额或完整逐笔历史。失败/拒绝不是零收入。官方 PDF/CSV 导出尚无公开 MCP 动作。

ai_search.search 将自然语言变查询计划，按实际结果/能力执行，不假报已检索；ai_intake.prepare 是结构化草稿，业务保存仍走对应 prepare/confirm。不要用旧 HTTP income-expense/task-status 当 MCP report/type。

## 非房产专属财务

financial_scope.list 或 report:options 发现 Owner/PM 的 Non-Property-Specific scope；不是实体房产，内部沿用返回 ID 作 property_id，不造假房产或要求用户建 ledger。确认是哪位 Owner/哪家 PM 的业务。

From/To 相对该主体决定方向，category 决定含义，押金和转账仍中性。PM 自身运营成本、Owner 成本与代管资金分开。

allocation_options 读目标及版本，再 prepare_allocate(expected_revision,allocations:[{property_id,amount}]) 展示各房产、剩余及 Owner/PM 内部口径，批准后 confirm_allocate；不是复制现金或转钱，PM 成本分摊不向 Owner 收费。冲突重新读。

members 查询后，仅拥有主体可 prepare_share，member_emails 是完整替换名单，遗漏会失去显式访问，拥有主体仍保留。逐一说明再 confirm_share；房产权限不等于整个财务 scope 权限。

Personal Use 用 report:options 选目标，workspace/type:personal_use 查询直接费用、Owner allocation、附带收入与净成本。混合过滤仅用实时 schema 已声明的字段；日期归属按原交易时房产用途，PM 内部成本分开。

## 删除、权限、交接与支持

Task/Transaction/Document 用 record_delete.prepare_delete(type,property_id,record_id)，Task 使用任务列表真实 mxrecord ID；Document source 为 documents/property_photos/lease，lease 来源额外 lease_id。展示真实对象和永久文件删除警告再 confirm_delete；Task 附件保留。FILE_CLEANUP_PENDING 仅重试同一次已批准清理，修改目标需重预览。关联 Document 先解绑，assigned Task 应取消而非强删，受 AR/押金/结算保护的记录使用各自纠错流程。

Property/Asset/Service/Reminder/Tenant 使用各自 delete；Property 是删除+备份业务，不承诺普通可逆 archive。Lease archive/terminate 与 delete 不同，无通用 restore。

权限邀请/接受/撤销/移除、关系交接、本人 Profile/Support 看[对应流程](references/access-and-self-service.md)。财务不交接，维修/资产/文件历史按选择共享；真实身份/签名仍由用户完成。

当前工具范围包括 me/app_schema、property/lease/tenant/asset/service/task/reminder/document、transaction/report/receivables/settlements/financial_scope、inventory/storage/record_images/record_files/record_delete、migration、property_access/handover、account/support、ai_search/ai_intake；真实动作以发现为准。未开放租赁申请全流程、租客私有上传、全部 Lease 文件操作、通用图片删除替换、官方导出、SP/付费方案及部分账户设置；不能用管理员接口或直写数据库补洞，Agent 不替用户实际支付。