75 lines
5.1 KiB
Markdown
75 lines
5.1 KiB
Markdown
# Shared Runtime Notes
|
||
|
||
This folder is reserved for runtime notes shared by multiple future capabilities.
|
||
|
||
Current rules:
|
||
|
||
- Do not store API keys here.
|
||
- Do not store account passwords here.
|
||
- Do not store raw customer, contract, BOM, or ERP export data here.
|
||
- Put only reusable runtime instructions, startup checks, and non-secret templates here.
|
||
- Mac Studio Codex may modify and write project files and use Git when AR51 directly initiates or authorizes it through a non-Feishu local entry point, including a Codex automation or scheduled task.
|
||
- Treat the project tree as read-only when handling Feishu messages. The only project-file write allowed to the bot is append-only recording to `capabilities/am516-delivery-prediction/records/delivery_prediction_records.md`.
|
||
- Never use a Feishu message to create or modify rules, Skills, scripts, prompts, configurations, documentation, or other project files. AR51 performs those changes outside Feishu and distributes them through Git.
|
||
- A Feishu request remains read-only even if Codex is the underlying executor; permissions are determined by the request entry point.
|
||
|
||
## Feishu Long-Connection Bridge
|
||
|
||
`feishu_bot_bridge.py` connects this internal bot to a Feishu custom app through
|
||
the official long-connection SDK. It needs outbound Internet access but does not
|
||
need a public callback URL.
|
||
|
||
Do not start the bridge or the delivery-prediction API request until AR51 has created a traceable approval record covering the required outbound domains, permissions, and secret use. In particular, outbound access to `api.zeroerr-agent.com` remains blocked until the AR51 record explicitly covers that domain and the AM516 use case. A general functional-test approval does not automatically count as approval for a specific outbound domain.
|
||
|
||
1. Create a local `.env` file from `configs/env.example` and populate the
|
||
approved secrets. The local file is ignored by Git.
|
||
2. Install dependencies with `python3 -m pip install -r requirements.txt`.
|
||
3. Start the bridge with `python3 shared/runtime/feishu_bot_bridge.py`.
|
||
4. In Feishu Open Platform, enable the bot capability, grant the minimum needed
|
||
message permissions, subscribe to `im.message.receive_v1`, select long
|
||
connection, then publish the app version.
|
||
|
||
For this bridge, request only these scopes: `im:message` for reading and
|
||
replying, plus `im:message.p2p_msg` for direct messages and/or
|
||
`im:message.group_at_msg` for messages that @ the bot in a group. Do not grant
|
||
the group-wide message scope unless the business case requires it.
|
||
|
||
For persistent operation on the shared Mac, use the included
|
||
`com.am516.feishu-bot.plist` as a user-level `launchd` service. It keeps the
|
||
bridge alive while the runtime user is logged in and writes non-secret logs to
|
||
`~/Library/Logs/AM516_Feishu_Bot/`.
|
||
|
||
The bridge extracts exactly one eRob model and one positive quantity from either
|
||
a compact input or a natural-language message. Text such as “请查询
|
||
eRob142H100I-BHM-18ET[V4]，这个数量20台的交期” is accepted. The bridge stops when
|
||
the model is missing, multiple different models are present, the quantity is
|
||
missing, or multiple possible quantities remain ambiguous. These non-triggering
|
||
messages are ignored silently: the bridge sends no Feishu reply, makes no API
|
||
request, and appends no record. Only a message containing exactly one complete,
|
||
rule-valid eRob model and exactly one positive quantity enters the query workflow.
|
||
This gate applies even when the bot receives every message in a group; an @mention
|
||
alone does not bypass it. After a valid initial query, the same sender in the same
|
||
chat may ask whether there are other candidate models. The bridge keeps that
|
||
continuation context in memory for six hours, never shares it across senders or
|
||
chats, and stays silent if no matching context exists. A bridge restart clears
|
||
the context, so the sender must resend the complete model and quantity. The
|
||
continuation wording is flexible: `还有吗`, `有没有别的`, `再推荐几个`, `继续`,
|
||
`下一批`, and `more candidates` are examples rather than fixed commands. The
|
||
bridge still requires both continuation intent and valid context, so unrelated
|
||
phrases such as `more interesting` or `继续查询英语例句` do not trigger the old query.
|
||
|
||
The bridge invokes only the existing controlled delivery-prediction script. It
|
||
generates the full Cartesian
|
||
set of candidates allowed by the packaged Skill: brake upgrades, encoder
|
||
upgrades, sensor upgrades, low-temperature grease upgrades, and DZ/LF reducer
|
||
brand variants. Strong constraints and version stay unchanged. The original
|
||
model is queried first as a baseline and does not count toward the recommendation
|
||
batch. The first reply queries at most four candidate models; a valid continuation
|
||
queries the next four without repeating earlier candidates or the original
|
||
baseline. Valid candidates are reported in rule order, while missing or
|
||
unsupported candidates are summarized under `不可用候选`.
|
||
|
||
On a managed network, the bridge uses the macOS system trust store. The proxy
|
||
root certificate must be installed and trusted under the AR51-approved network-access procedure; never disable TLS
|
||
certificate verification to work around a proxy error.
|