Skip to content

أعطها أدوات حقيقية ​

الجمع مجرد عرض توضيحي. في هذا القسم نستبدله بأدوات مفيدة حقًا: قراءة الملفات وكتابتها، وتشغيل الأوامر، وجلب صفحات الويب. بعد الانتهاء سيكون لديك أول نسخة قابلة للاستخدام من myagent، وستعرف كيف تمنعه من إحداث فوضى.

حمّل الكود الكامل myagent.zip، وبعد فك الضغط ادخل إلى مجلد myagent. هذا القسم يغطي النصف الأول من agent.py.

الأداة هي مجرد دالة عادية ​

python
def list_dir(path="."):
    return "\n".join(sorted(p.name + ("/" if p.is_dir() else "") for p in Path(path).iterdir()))

def read_file(path):
    return Path(path).read_text(encoding="utf-8")[:8000]

def fetch_url(url):
    req = urllib.request.Request(url, headers={"User-Agent": "myagent/1.0"})
    html = urllib.request.urlopen(req, timeout=20).read().decode("utf-8", "ignore")
    text = re.sub(r"<script.*?</script>|<style.*?</style>|<[^>]+>", " ", html, flags=re.S)
    return re.sub(r"\s+", " ", text)[:6000]

لاحظ أن قيمة إرجاع كل أداة مقتطعة (8000 حرفًا، 6000 حرفًا). تُدرَج نتائج الأدوات كما هي في المحادثة، وقد يؤدي ملف كبير واحد إلى تفجير سياق النموذج.

الأدوات الخطرة، اسأل أولًا ​

كتابة الملفات وتشغيل الأوامر تُغيّر حاسوبك. اسأل سؤالًا داخل الدالة أولًا:

python
def ask(question):                                  # 危险操作先问人
    return input(f"\n⚠️  {question} [y/N] ").strip().lower() == "y"

def run_shell(command):
    if not ask(f"运行命令:{command}"):
        return "用户拒绝了运行。"
    r = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=60)
    return (r.stdout + r.stderr)[-4000:] or f"(没有输出,退出码 {r.returncode})"

الرفض ليس خطأً أيضًا، بل جملة "المستخدم رفض التشغيل" تُعاد إلى النموذج ليجرب طريقة أخرى أو يسألك.

جرّبنا ذلك فعلًا، وطلبنا منه "حذف مجلد worklog"، وأدخلنا n عند التأكيد:

text
  [1] list_dir({"path": "./worklog"})
  [2] run_shell({"command": "rm -rf ./worklog"})

⚠️  تشغيل الأمر: rm -rf ./worklog [y/N] n
الوكيل: هل أنت متأكد من حذف مجلد worklog؟ ستُحذف الملفات نهائيًا ولا يمكن استعادتها. يُنصح بنسخ الملفات احتياطيًا أولًا…

المجلد ما زال موجودًا. لهذا قلنا في القسم السابق إن "النموذج يطلب فقط، وحق التنفيذ بيدك": التحكم في الصلاحيات يُكتب هنا.

أخبر النموذج بالأدوات المتاحة ​

لكل أداة فقرة توضيحية. عندما تكثر الأدوات، يصبح كتابة JSON Schema يدويًا أمرًا مطولًا، فاكتب دالة صغيرة لتوليدها:

python
def spec(tool_name, desc, **params):
    return {"type": "function", "function": {"name": tool_name, "description": desc, "parameters": {
        "type": "object", "properties": {k: {"type": "string", "description": v} for k, v in params.items()},
        "required": list(params)}}}

TOOLS = [
    spec("list_dir", "列出目录里的文件", path="目录路径"),
    spec("read_file", "读取一个文本文件的内容", path="文件路径"),
    spec("write_file", "写入文本文件(会先请用户确认)", path="文件路径", content="完整内容"),
    spec("run_shell", "在终端运行一条命令(会先请用户确认)", command="要运行的命令"),
    spec("fetch_url", "抓取网页并返回纯文本", url="网址"),
]

في النسخة الأولى التي كتبناها سمّينا المعامل الأول لهذه الدالة name، فأبلغ spec("load_skill", ..., name="技能名") مباشرة عن الخطأ got multiple values for argument 'name': معامل الأداة نفسه يسمى name أيضًا. لذلك غيّرناه إلى tool_name.

شغّله ​

bash
python agent.py "看看 worklog 文件夹里有哪些文件"

من المفترض أن ترى:

text
  [1] list_dir({"path": "worklog"})

الوكيل: يحتوي مجلد worklog على الملفات التالية:
- 11-16.txt
- 11-18.txt
- 11-20.txt

النموذج يخطئ، لذا يجب إعادة الأخطاء إليه ​

في ذلك التشغيل الحقيقي الموجود في صفحة الدرس الرئيسية، كتب النموذج في أول محاولة لقراءة الملف /worklog/11-16.txt (بشرطة مائلة زائدة في البداية)، فحصل على:

text
出错了:FileNotFoundError: [Errno 2] No such file or directory: '/worklog/11-16.txt'

لأننا أعدنا رسالة الخطأ كما هي، ذهب في الخطوة التالية إلى list_dir ليلقي نظرة، ثم قرأ بشكل صحيح باستخدام ./worklog/11-16.txt. لو انهار البرنامج هنا مباشرة، لفشلت المهمة بأكملها.

تذكر Anthropic في مقال «Building effective agents» أنهم يقضون في صقل الأدوات وقتًا أكثر مما يقضونه في صقل التعليمات، مثل تعديل الأداة لتشترط استخدام المسارات المطلقة. كلما كانت توضيحات الأداة ومعلومات الإرجاع أوضح، قلّت أخطاء النموذج.

ابحثعند تصميم الأدوات……

انقر على واحد لترى.

اختبر معرفتكرفض المستخدم أمر rm -rf عند التأكيد، فماذا يجب أن يفعل البرنامج؟

تحقق ​

  • شغّلت list_dir بنجاح، ورأيت قائمة الملفات
  • جربت الرفض مرة run_shell، والملف سالم
  • أستطيع ذكر أربع نقاط أساسية في تصميم الأدوات

القسم التالي: الذاكرة: اجعله يتذكر السياق.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.